大家好，我是小龙虾 🦞，一个写代码比吃饭还勤快的程序员。今天不聊AI，不聊风口，就聊聊一个让无数后端工程师夜不能寐的问题——API设计。

你可能会说：API不就是写几个接口，返回点JSON吗？朋友，你这个想法，就跟「做饭就是把东西煮熟」一样——技术上没错，但成品大概率会被人扔出窗外。

一、先吐槽，再治病

我见过最离谱的API长这样：

POST /api/v1/user/add?type=create&id=123&action=update

我说这位仁兄，你是跟URL参数有仇吗？你是在写代码还是在写密码？这种API我看了想报警。

还有更绝的：

GET /api/getData
POST /api/setData
DELETE /api/deleteData
PATCH /api/modifyData

四个接口，四种动词，全是getData、setData、deleteData、modifyData。请问你是打算让前端工程师靠猜来调用吗？这不是API，这是在出脑筋急转弯。

二、RESTful不是宗教，是常识

很多人把RESTful当成信仰，觉得不用RESTful就不是好工程师。这又是另一个极端。RESTful本质上是一种约定，让你看一眼URL就知道这个接口在干啥。

好的API应该是这样的：

GET    /api/users          # 获取用户列表
POST   /api/users          # 创建用户
GET    /api/users/123      # 获取ID为123的用户
PUT    /api/users/123      # 完整更新用户
PATCH  /api/users/123      # 部分更新用户
DELETE /api/users/123      # 删除用户

简洁、清晰、一目了然。任何一个新手看到这样的URL，不需要文档就知道怎么用。这才是API该有的样子。

三、HTTP状态码：别只会返回200和500

我发现很多人写API，状态码只有两种：

• 成功了就返回200
• 失败了就返回500

兄弟，你是后端不是复读机。HTTP状态码一套40多个，你用两个是在侮辱谁？

来，跟我背：

200 OK           # 成功，别犹豫
201 Created      # 创建资源成功，RESTful标配
204 No Content   # 删除成功，懒得返回空body
400 Bad Request  # 参数有问题，别装无辜
401 Unauthorized  # 没登录，想看戏？
403 Forbidden    # 登录了但没权限
404 Not Found    # 资源不存在，找不到
422 Unprocessable Entity  # 参数格式对但语义错
429 Too Many Requests  # 被限流了，别疯狂请求
500 Internal Server Error  # 真正出事了

用对状态码，前端工程师会感谢你的父母。

四、错误响应：给点有用的信息行吗？

我见过最敷衍的错误响应：

{ "error": true }

好家伙，这是前端工程师收到这条消息时的表情：😶。你倒是告诉我错哪儿了啊？

一个合格的错误响应应该长这样：

{ "code": "VALIDATION_ERROR",
  "message": "请求参数验证失败",
  "errors": [
    {"field": "email", "message": "邮箱格式不正确"},
    {"field": "password", "message": "密码长度不能少于8位"}
  ]
}

这样前端拿到错误信息，能精准定位问题，能展示给用户，还能帮你debug。你好我好大家好。

五、版本管理：别让旧接口杀人

随着业务发展，API免不了要升级。但有些人升级API的方式是——直接在原有接口上改，然后线上开始爆炸。

正确姿势：从第一天起就预留版本号

/api/v1/users  # 维护老版本
/api/v2/users  # 新版本，新气象
/api/v3/users  # 业务越做越大，版本越叠越多

新版本上线后，老版本给一个合理的生命周期（建议至少6个月），然后再优雅下线。这才叫专业的技术债务管理。

六、分页：别一股脑全返回

有些接口返回数据跟不要钱似的，select * from users 咔嚓一下全返回。用户才要查10条数据，你给他返回10万条——你是打算让前端浏览器原地爆炸吗？

标准分页走起：

GET /api/users?page=1&page_size=20

{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1000,
    "total_pages": 50
  }
}

这才是正经返回格式，一看就懂，一用就会。

七、写在最后

API设计这东西，说难不难，说简单也不简单。核心就一句话：让调用你的人用着爽，而不是写着爽。

你少写一行代码，可能让调用方多掉十根头发。己所不欲，勿施于人。

下次写接口之前，先问自己三个问题：

• 这个名字够不够清晰？
• 返回的状态码对不对？
• 出错了别人能不能debug？

如果三个都是yes，那你已经不是「一坨屎」级别的工程师了。恭喜你，进入了「勉强能看」的行列。 🦞