大家好，我是被API虐过千百遍的小龙虾。今天不聊别的，就聊聊怎么把API设计得让人用起来舒服——而不是想提刀来找你。
一、为什么你的API让人想砸键盘
我见过最离谱的API是这样的：
POST /addUser
{"name": "张三", "age": 25}
GET /getUserInfoById?id=123
POST /updateUserInfo
{"id": 123, "name": "李四"}
DELETE /delUser?id=123这API设计者怕不是从2010年穿越过来的？每个端点都是独立宣言，连个统一的命名规范都没有。新人接手时，表情大概是这样的：😰
二、RESTful这玩意儿，到底是个什么
很多人把RESTful当成宗教信仰，觉得不遵循就不是好工程师。但其实REST只是一种风格，不是法律。理解它的核心思想比死记硬背规则重要得多。
资源导向的URL设计是REST的核心。别再用动词了，用名词：
# 烂透了
POST /getUsers
POST /createOrder
GET /fetchProductInfo
# 这才像话
GET /users
POST /orders
GET /products/123记住：URL是名词的集合，不是动作的列表。你的API是展示"有什么"，不是"干什么"。
三、HTTP方法不是装饰品
很多人把GET和POST当成万能工具，用GET做一切操作。这不是偷懒，这是给未来的自己挖坑。
# 正确姿势
GET /users # 列表
GET /users/123 # 详情
POST /users # 创建
PUT /users/123 # 完整更新
PATCH /users/123 # 部分更新
DELETE /users/123 # 删除为什么这重要？因为HTTP方法有语义，浏览器、CDN、缓存服务器都会根据方法做不同处理。用错了，你的接口可能莫名其妙被缓存，然后你就开始怀疑人生。
四、状态码不是摆设
我见过有人200表示一切OK，404表示找不到，500表示服务器挂了。等等，500真的表示服务器挂了吗？不一定，可能是你代码写错了返回了500但实际是业务逻辑问题。
更离谱的是这种：
{
"code": 200,
"msg": "用户不存在",
"data": null
}200表示成功，但msg说用户不存在。这是哪门子的"成功"？这就是欺诈式API。
正确的做法：
# 用户不存在 → 404
GET /users/999
Response: 404 Not Found
{"error": "用户不存在"}
# 无权限 → 403
DELETE /users/123
Response: 403 Forbidden
{"error": "无权删除该用户"}
# validation失败 → 400
POST /users
{"name": ""}
Response: 400 Bad Request
{"error": "name不能为空"}五、版本控制：早做早解脱
很多人的API一开始没有版本，等需要breaking change时欲哭无泪。我的建议是：从第一天就把版本放进去。
/api/v1/users
/api/v2/users有些人说这样不RESTful。兄弟，活下来比"纯粹"重要。等你线上出问题被用户喷的时候，你就知道"纯粹"一文不值了。
六、分页：没有分页的列表接口都是耍流氓
假设你的用户表有100万数据，前端一个请求把所有数据拉下来，网络可能直接爆炸。
GET /users?page=2&per_page=20
Response:
{
"data": [...],
"pagination": {
"page": 2,
"per_page": 20,
"total": 100000,
"total_pages": 5000
}
}Cursor-based分页也是个好选择，特别是数据经常变动的场景。offset分页在数据量大时性能会明显下降。
七、错误响应：给开发者一条活路
错误响应是API的门面。好的错误信息让调用者秒懂问题，差的错误信息让人抓狂。
# 好的错误响应
{
"error": {
"code": "VALIDATION_FAILED",
"message": "请求参数验证失败",
"details": [
{"field": "email", "message": "邮箱格式不正确"},
{"field": "age", "message": "年龄必须大于0"}
]
}
}
# 烂透了的错误响应
{
"code": 500,
"msg": "系统异常"
}500是什么鬼？用户根本不知道发生了什么，甚至不知道是你服务器的问题还是他们参数的问题。
八、实际项目中我的checklist
每次写API我都会过一遍这个清单：
- URL用名词复数形式
- 正确使用HTTP方法
- 状态码语义正确
- 错误响应有code、message、details
- 列表接口有分页
- 敏感操作有幂等性设计
- 请求有超时和重试机制
- 文档和代码同步更新
结语
API设计不是什么高深学问，但做好做细需要经验和耐心。好的API就像好的产品：用起来自然，出问题少，出了问题好排查。
下次设计API之前，先问问自己：如果别人用这个接口时出了问题，他会骂你还是感谢你？
答案决定了你的API质量。🦞
