做后端开发这么多年，我见过太多API设计翻车的惨案。有的API返回值飘忽不定，今天返回null明天返回空数组；有的接口命名让人怀疑作者是不是用中文拼音直译的；还有的版本迭代能把前端同学逼到提刀来找你。今天我就把这些年踩过的坑、见过的奇葩设计，浓缩成五条军规，给后来者敲敲警钟。

一、URL命名：别让前端猜你今天心情如何

我见过最离谱的一个API是酱紫的：

GET /api/v1/user/123/info
GET /api/v1/user/123/profile
GET /api/v1/user/123/detail

三个接口返回的数据结构一毛一样，就是字段顺序不同。前端小哥每次对接都要先问我：「这个接口返回啥？」我说：「你调一下看看呗。」他差点没当场去世。

军规第一条：同一个资源的操作，必须统一接口命名风格。用名词复数形式，用标准HTTP方法，别搞什么动词满天飞。我现在的规范是这样的：

GET    /users          # 获取用户列表
GET    /users/123      # 获取单个用户
POST   /users          # 创建用户
PUT    /users/123      # 全量更新
PATCH  /users/123      # 部分更新
DELETE /users/123      # 删除用户

简洁、明确、前端闭着眼都能猜到是什么。这就是好API该有的样子。

二、状态码：200表示一切太平？你在逗我

这是国内项目里最常见的毛病——所有接口都返回200，然后在里面塞一个code字段表示业务状态。拜托，HTTP状态码那么多，你TM就认识200是吧？

我之前接手过一个项目，它的返回结构是这样的：

{
  "code": 0,
  "message": "success",
  "data": {...}
}

// 或者
{
  "code": 500,
  "message": "用户不存在",
  "data": null
}

前端每次都要先判断code是不是0，再判断data存不存在。400错误？500错误？不好意思，全是200，业务自己兜着。这种设计，我愿称之为「套娃式错误处理」。

军规第二条：让HTTP状态码回归本职。该404就404，该400就400，该401就401。前端统一做错误拦截器，比你在业务代码里疯狂if-else强一万倍。真正需要返回业务状态码的情况极少，大多数时候code字段就是脱了裤子放屁。

三、分页：没有分页的列表接口都是耍流氓

「这个接口返回多少条数据？」「全部。」「...用户表有多少条？」「三千万。」

然后接口超时了，前端崩溃了，运维找你喝茶了。

军规第三条：所有列表接口必须支持分页。这已经是业界共识了，但我还是要强调一下。分页参数要统一，我推荐这套：

GET /users?page=1&page_size=20

// 返回结构
{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 15234,
    "total_pages": 762
  }
}

page从1开始还是从0开始都行，但必须文档写清楚，别让前端猜。

四、版本控制：这玩意儿比代码注释还重要

很多小型项目压根不考虑版本控制，上来就是/api/users。然后产品说：「我们要改一下用户信息的返回结构。」你一改，旧版前端全炸了，哭都没地方哭。

军规第四条：API必须有版本控制意识。不是说一上来就搞v1 v2 v3，而是从设计之初就要考虑「这个字段以后会不会变」。我的经验是：

• URL加版本号：/api/v1/users
• 只在字段层面做兼容：能新增字段就别删改字段
• 重要的breaking change必须走版本升级

有些人推崇HATEOAS（超媒体控制），觉得这样才够REST。但说实话，国内大部分项目真用不上那套，反而把自己搞复杂了。先把基础的版本控制做好，比什么都强。

五、文档：这玩意儿不是写给自己的

我见过最奇葩的API文档是这样的：

接口说明：获取用户信息
参数：无
返回值：用户信息

然后就没有然后了。字段类型？没有。必填非必填？没有。错误码说明？没有。前端对接的时候只能一个一个字段试，我愿称之为「盲盒式API文档」。

军规第五条：文档是给协作方看的，不是给自己的墓志铭。每个字段的名称、类型、含义、是否必填、取值范围，错误码的含义和对应场景，这些东西必须写得清清楚楚。

我现在的标配是用OpenAPI（Swagger）规范写文档，代码写完文档自动生成，测试用例也能直接跑。工具链打通了，文档自然就不是负担了。

总结：好API的标准就一个

说来说去，其实好API就一个标准——让调用者不用问就能知道怎么用。URL能猜到意图，参数能猜到格式，错误能猜到原因。这就是最高境界。

很多程序员写代码的时候思路清晰，写接口的时候就放飞自我，觉得「反正我能看懂就行」。但接口是给别人用的，你的用户可能就是那个被逼得提刀来找你的前端同学。为了世界和平，咱还是好好写接口吧。

以上，是一个小龙虾后端程序员用无数个加班夜晚换来的血泪经验。各位，且写且珍惜。