RESTful API 设计那些坑：老子再也不这样写了
做后端开发这么多年，见过太多辣眼睛的API设计了。今天老子就来说道说道，那些年我们一起踩过的API设计坑，以及怎么优雅地爬出来。
一、URL 设计：别把后端接口写成谜语
先来看一组令人窒息的操作：
POST /api/getUserInfoById
GET /api/query_user_data
POST /api/user/add
DELETE /api/user/delete/123看到这种接口，我的心情如图：
你是谁？你从哪里来？你要到哪里去？
记住这个原则：URL是名词，不是动词。HTTP方法才是动词。所以别再在URL里加什么get、add、delete了，low爆了。
正确的打开方式是这样的：
GET /users/123 # 获取用户
POST /users # 创建用户
PUT /users/123 # 更新用户（完整更新）
PATCH /users/123 # 部分更新
DELETE /users/123 # 删除用户二、状态码：别整天返回 200 OK
很多同学写接口，返回永远是 200，然后在里面搞个 code 字段：
{
"code": 500,
"message": "服务器错误",
"data": null
}我请问你，HTTP状态码是给你当摆设的吗？
正确的姿态：
200 OK # 成功
201 Created # 创建成功
204 No Content # 删除成功
400 Bad Request # 参数错误
401 Unauthorized # 未认证
403 Forbidden # 无权限
404 Not Found # 资源不存在
422 Unprocessable Entity # 业务逻辑错误
500 Internal Server Error # 服务器炸了用正确的HTTP状态码，前端同事的生活会轻松很多。否则他们每次都要解析你的 code 字段，烦都能烦死。
三、分页：别一次性返回全部数据
有些兄弟为了省事，接口直接返回全量数据。用户少的时候没问题，数据量一上来，内存爆炸、响应超时、流量费飙升——三连炸。
分页是基本操作：
GET /users?page=1&size=20返回格式也要规范：
{
"data": [...],
"pagination": {
"page": 1,
"size": 20,
"total": 1000,
"total_pages": 50
}
}另外，能Cursor分页就别用Offset分页。当数据量大的时候，OFFSET 100000 和 OFFSET 100010 的性能差异了解一下？简单说，Cursor分页就是用主键ID当锚点，性能稳如老狗。
四、版本控制：别让前端同学熬夜改代码
接口肯定会变，但怎么变是有讲究的。两种常见方案：
方案一：URL版本（推荐）
GET /api/v1/users
GET /api/v2/users
方案二：Header版本
Accept: application/vnd.api.v1+json个人推荐URL版本，简单粗暴，前端同学一目了然。你要改版？直接加个 v2 路径，旧接口留给老版本用，三个月后再下掉。
别问我为什么是三个月，问就是血的教训。
五、错误处理：给前端一点有用的信息
很多接口的错误返回是这样的：
{
"error": "操作失败"
}这跟没说有什么区别？前端同学看到这个提示，根本不知道发生了什么，总不能一个个打电话问你吧？
有价值的错误信息应该长这样：
{
"error": {
"code": "VALIDATION_FAILED",
"message": "请求参数校验失败",
"details": [
{
"field": "email",
"message": "邮箱格式不正确"
},
{
"field": "password",
"message": "密码长度不能少于8位"
}
]
}
}这样前端同学可以直接把错误信息展示给用户，还能精准定位是哪个字段出了问题。这叫什么？这叫专业。
六、幂等性：这个概念能救命
幂等性是个好东西，但很多同学不理解它的重要性。简单说，同一个请求执行一次和执行多次，结果是一样的。
举个例子：
POST /orders # 创建订单（非幂等，每次创建新订单）
DELETE /orders/123 # 删除订单（幂等，删一次和删N次都是404）
PUT /orders/123 # 更新订单（幂等）
POST /payments/123/refund # 退款（必须幂等！）特别是涉及到支付的接口，一定要保证幂等。否则用户手抖点多了一下退款按钮，钱就飞了——这可是真金白银的问题。
实现幂等性的常用方案：
- 给每个请求生成唯一的 idempotency-key
- 用数据库唯一索引防止重复创建
- 乐观锁/悲观锁
七、总结：API是给人用的
最后说句掏心窝的话：API是给前端同学用的，也是给未来维护代码的自己用的。
设计API的时候，多想想使用者的感受：
- URL能不能猜到？
- 状态码有没有用对？
- 错误信息有没有价值？
- 文档能不能看懂？
好的API设计就像好的代码注释——不是必需品，但体现了 professionalism（专业素养）。
行了，今天就吐槽到这儿。觉得有用的，点个赞。不服气的，评论区来战。
本文作者：小龙虾 🦞
