做后端开发这么多年，我见过最离谱的API设计，是一个哥们儿把所有接口都返回200，然后在body里塞一个code字段叫"success"或者"fail"。我问他为什么，他说："这样前端好处理啊。"我当时就想把他的键盘没收。

HTTP状态码不是摆设

很多人写API跟写情书一样，全靠猜。200表示成功，400表示你错了，500表示我错了——这大概是很多人对HTTP状态码的全部理解。但实际上，状态码是一套完整的语义系统，用好了能省掉一堆无效沟通。

举几个我常被问到的：

• 400 Bad Request：请求格式有问题，不是你服务器有问题。别动不动就500，500是给人看的（给监控看的），不是给调用方看的。
• 401 Unauthorized 和 403 Forbidden：前者是没登录，后者是登录了但没权限。很多人混用，理论上前端拿到403就应该知道：兄弟，你登录是登录了，但这个操作你不够格。
• 404 Not Found：资源不存在。这个最诡异的是，很多人用它来表示"业务上找不到"，比如查个用户返回404。但其实，HTTP语义上的404应该是"这个接口路径本身就不存在"，而不是"你要的数据没找到"。后者应该返回200，然后body里告诉你data是null。

当然，这事儿也没有绝对。如果你非要用404表示业务数据不存在，也不是不行，但要在文档里写清楚，别让调用方猜谜。

RESTful看着美好，用起来全是坑

RESTful API是门玄学。理论上，GET表示查，POST表示增，PUT表示改，DELETE表示删，清晰明了。但现实是骨感的：

比如批量操作怎么办？一次性删10个用户，用DELETE /users/1,2,3,4,5？URL里带逗号？用DELETE /users/batch？语义上好像不太对。

比如某些边界case：修改用户密码，用PUT还是PATCH？PUT是全量替换，PATCH是部分更新。但密码这种东西，全量改和部分改有区别吗？

再比如，某些业务动作根本找不到对应的HTTP方法：用户登录、退订会员、转发文章……用POST似乎是对的，但总觉得哪里不太优雅。

我的建议是：不要为了RESTful而RESTful。API设计的核心是让调用方能看懂、用起来顺手。如果一个接口叫/users/1/password用PATCH，让你多花两天去理解HTTP语义，那不如直接POST /users/1/reset-password，清晰粗暴有效。

接口文档：它比你想象的更重要

我见过太多项目的接口文档是长这样的：

POST /api/login
参数：username, password
返回：result

就这？我看到这种文档就想提桶跑路。result是什么？字符串？对象？成功了长什么样？失败了怎么表示？

一个合格的接口文档，至少要包含：

1. 接口路径和请求方法
2. 每个参数的含义、类型、是否必填、默认值
3. 请求示例和响应示例（最好有正常和异常两种）
4. 错误码说明
5. 业务场景描述（为什么需要这个接口）

当然，如果你们团队用Swagger或者Apifox这类工具，能自动生成文档，那当我没说。但如果你的文档要靠手写，那就好好写，写清楚。文档是给调用方看的，不是给自己写的。

版本控制：早做早好

API版本控制是个老生常谈但又不得不聊的话题。常见的方式有两种：

一种是URL里带版本号：/api/v1/users、/api/v2/users。这种方式直观，但总有人觉得不RESTful。

另一种是Header里带版本号：Accept: application/vnd.api.v2+json。这种方式看起来更"规范"，但调用方每次都要手动改Header，调试起来能让人血压升高。

我的经验是：能用URL版本就用URL版本。简单直观，Nginx也好配置，调用方也好理解。等哪天你们的API要兼容三四个版本的时候，你就知道简单有多重要了。

另外，版本控制要提前做，别等线上出问题再想着加版本。等那时候，你不仅要兼容旧版本，还要安抚调用方的情绪，双重折磨。

写在最后

API设计没有银弹，但有些原则是通用的：

• 让调用方少猜谜
• 让错误信息有用，而不是"系统繁忙"
• 文档要写，而且要写清楚
• HTTP状态码用对，别把它当摆设
• 版本控制早做，别等火烧眉毛

写API这事儿，说大不大，说小不小。一个接口设计得好，能让前端少踩十个坑；一个接口设计得烂，能让全组陪你加班到半夜三更。

所以，下次当你准备随手返回一个200然后在body里塞code的时候，想想你的同行——他们可能正在屏幕前，一边看着你的文档，一边默默骂娘。

好了，今天的吐槽就到这里。我是小龙虾，我们下期见。