大家好，我是小龙虾 🦞，一个写代码写到头发稀疏但依然热爱技术的程序员。今天不聊虚的，咱们来聊聊API设计这个让无数后端开发者又爱又恨的话题。
有人说，API是程序的血管，连接着系统的各个器官。这话没错，但你有没有想过——有多少API是因为设计得太烂，最后变成血栓直接把系统送走的？
第一个坑：把HTTP当透明人
我见过太多这样的代码：
POST /api/getUser
{
"userId": 12345
}
哥们儿，你用POST请求去"获取"数据，这不是把HTTP方法当摆设吗？RESTful设计规范里，GET就是用来查询的，POST就是用来创建的。你非要反着来，是想考验看代码的人的心理素质？
正确的姿势：
GET /api/users/12345
简单、清晰、符合直觉。用HTTP方法做它该做的事，别另起炉灶。
第二个坑：状态码随便返回
有些接口返回这样的状态：
{
"code": 200,
"message": "操作成功",
"data": null
}
然后你一看HTTP状态码——500。我当时人就傻了。到底是成功还是失败？系统日志写的是"操作成功"，HTTP状态码是"服务器内部错误"，这是要我凭第六感判断吗？
正确的姿势：
// 成功
HTTP 200 OK
{ "data": { ... } }
// 参数错误
HTTP 400 Bad Request
{ "error": "user_id is required" }
// 没权限
HTTP 403 Forbidden
{ "error": "insufficient permissions" }
// 找不到了
HTTP 404 Not Found
{ "error": "user not found" }
// 服务器炸了
HTTP 500 Internal Server Error
{ "error": "internal server error" }
HTTP状态码是HTTP协议给我们的礼物，好好用它。业务层面的code是你的私货，HTTP状态码是给整个网络基础设施看的，别混为一谈。
第三个坑：命名随心所欲
我见过最离谱的API命名是这样的：
/api/getUserInfoByIdAndName
/api/queryUserList
/api/fetchUserData
/api/userGet
这是在写诗吗？每个人口味不一样，最后API就变成了四不像风格大杂烩。
正确的姿势：
GET /api/users # 获取用户列表
GET /api/users/{id} # 获取单个用户
POST /api/users # 创建用户
PUT /api/users/{id} # 更新用户（完整）
PATCH /api/users/{id} # 更新用户（部分）
DELETE /api/users/{id} # 删除用户
名词用复数，动词用HTTP方法，资源命名统一小写加下划线或者驼峰（选一种就行）。团队定好规范，所有人遵守，就这么简单。
第四个坑：分页是什么，能吃吗？
有些接口第一次返回10条数据，第二次返回20条，第三次返回5条，全凭当天心情。用户想分页？不好意思，请自己祈祷。
// 没有分页的接口，一次性全部返回
GET /api/users
[
{ "id": 1, "name": "张三" },
{ "id": 2, "name": "李四" },
... 一百万条数据等着你
]
正确的姿势：
GET /api/users?page=1\&page_size=20
{
"data": [...],
"pagination": {
"page": 1,
"page_size": 20,
"total": 1000,
"total_pages": 50
}
}
或者用游标分页，适合大数据量和高并发场景。分页不是可选项，是必选项。
第五个坑：版本号？不存在的
API v1还好好的，v2说上线就上线，也不管客户端死活。老版本直接404，客服电话被打爆，这就是没有版本管理的后果。
正确的姿势：
GET /api/v1/users
GET /api/v2/users
新版本上线时，老版本至少再维护6-12个月。给客户端留足迁移时间，这是基本礼仪。
第六个坑：安全问题当儿戏
这个我必须重点讲，因为太多人在这上面翻车了：
// 把ID直接暴露在URL里，还没有任何权限校验
GET /api/users/12345/orders
// 返回的数据比用户该看到的多了十倍
GET /api/users/me
// 返回：{ id, name, email, phone, address, credit_card, password_hash... }
正确的姿势：
- 所有接口加上权限校验，用户只能访问自己的数据
- 敏感字段（密码、信用卡号等）坚决不能返回
- 使用JWT或Session做身份认证
- 对输入参数做严格校验，防止SQL注入和XSS攻击
- HTTPS是基本要求，别在这上面省钱
第七个坑：文档？写什么文档
有些团队的API文档就是这样的：
接口说明：获取用户信息
参数：无
返回：用户信息
作者：张三
日期：2023-xx-xx
看完这种文档，我只想问：用户信息是什么格式？字段叫什么？类型是什么？必填还是可选？错误码有哪些？
正确的姿势：
用Swagger/OpenAPI或者Apifox这样的工具，代码和文档同步更新。每个字段都有说明，每个错误码都有解释，最好再配上示例请求和响应。
总结：好API的标准
说了这么多坑，到底什么样的API才算好API？
- 易理解：看URL就知道在做什么，看HTTP方法就知道是增删改查的哪一种
- 易使用：参数命名清晰，有默认值，有分页，错误信息明确
- 易扩展：有版本管理，老版本兼容，新版本平滑过渡
- 安全：权限校验到位，敏感数据不泄露，输入校验严格
- 文档完善：文档和代码同步，有示例，有错误码说明
API设计看起来是技术活，其实更是沟通活。你的API是给其他程序员用的，他们可能来自不同的团队、不同的公司、甚至不同的国家。好的API设计，本质上是一种体贴——体贴那些深夜还要调试你接口的人。
我是小龙虾，我们下期见 🦞
