你的API为什么这么难用？谈谈RESTful设计的那些坑
作为后端开发者，我见过太多”能用但难用”的API。有的返回格式随心所欲，有的错误码像天书，有的文档永远停留在v1.0版本。今天，我想聊聊那些让前端同事抓狂的API设计问题，以及如何避开这些坑。
坑一：动词当成名词用
最常见的错误之一，就是在URL里塞动词：
/api/getUserInfo
/api/createOrder
/api/deleteProduct这不是RESTful，这是RPC风格的URL。在RESTful设计中，URL应该表示资源（名词），HTTP方法表示操作（动词）。正确的写法应该是：
GET /api/users/{id} # 获取用户信息
POST /api/orders # 创建订单
DELETE /api/products/{id} # 删除产品坑二：状态码只用200和500
有些API不管成功失败都返回200，然后在响应体里用code字段表示真正的状态：
// HTTP 200 OK
{
"code": 40001,
"message": "用户不存在"
}这种设计让HTTP状态码形同虚设。正确的做法是充分利用HTTP状态码：
200 OK - 请求成功
201 Created - 资源创建成功
400 Bad Request - 参数错误
401 Unauthorized - 未认证
404 Not Found - 资源不存在
500 Internal Server Error - 服务器错误坑三：错误信息不够友好
当API返回错误时，”系统错误”这四个字可能是最没用的信息。好的错误信息应该告诉调用者：
- 发生了什么：参数password不能为空
- 为什么发生：密码长度必须在8-20位之间
- 怎么解决：请检查password字段是否正确填写
一个结构化的错误响应示例：
{
"error": {
"code": "VALIDATION_ERROR",
"message": "参数验证失败",
"details": [
{
"field": "password",
"rule": "min_length",
"expected": 8,
"actual": 5
}
]
}
}坑四：版本控制缺失
API一旦发布，就会有人调用。当你需要修改接口时，没有版本控制就是灾难现场。常见的版本控制方式：
# URL路径版本
/api/v1/users
/api/v2/users
# HTTP Header版本
Accept: application/vnd.myapi.v2+json推荐使用URL路径版本，简单直观，调用方一目了然。
坑五：分页和过滤设计混乱
列表接口的分页参数五花八门：有的用page/size，有的用offset/limit，有的干脆让前端自己算偏移量。建议遵循统一规范：
# 分页
GET /api/users?page=1&size=20
# 排序
GET /api/users?sort=created_at&order=desc
# 过滤
GET /api/users?status=active&role=admin响应中包含分页元信息：
{
"data": [...],
"pagination": {
"page": 1,
"size": 20,
"total": 156,
"total_pages": 8
}
}总结：好的API应该像好用的说明书
一个好的API，应该让新来的开发者看一眼就能上手，而不需要反复追问”这个接口返回什么”、”那个错误是什么意思”。
记住几个核心原则：
- URL是名词，HTTP方法是动词
- 用好HTTP状态码
- 错误信息要有价值
- 版本控制不能少
- 接口要一致、可预测
好的API设计不是一蹴而就的，需要在实践中不断打磨。当你开始站在调用者的角度思考问题时，你的API就会越来越好用。
觉得有用就点个赞吧~