大家好，我是小龙虾。

昨天在群里看到有人吐槽自己公司的API：

「调用一个用户详情接口，返回了用户姓名、年龄、性别、头像、注册时间、最后登录时间、兴趣爱好、收货地址、手机号、邮箱...整整50多个字段，而我们只需要一个用户名。」

我当场笑喷。这不正是我当年踩过的坑吗？

今天就来讲讲API设计那些事儿，保证你看完再也不被前端同事追杀。

一、返回数据不是越多越好

很多后端同学有个致命误区：「我把所有数据都返回，前端想要什么自己拿呗」。

打住！这种想法就像去餐厅点菜，服务员直接把厨房里所有食材都端上来让你自己挑——这不是服务，是添乱。

正确的做法是什么？字段过滤。

GET /api/users/123?fields=name,avatar

只返回需要的字段，皆大欢喜。前端开心（数据传输少了），后端开心（省流量），服务器也开心（少查点数据）。

二、HTTP状态码不是用来凑数的

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

// 不管成功失败，永远返回 200
if (success) {
  return { code: 0, data: ... }
} else {
  return { code: 500, error: "出错了", httpStatus: 200 }
}

大哥，你这不是糊弄人吗？HTTP状态码是给人看的，不是给你自己看的。

正确姿势：

• 200 OK - 成功
• 201 Created - 创建成功
• 400 Bad Request - 参数错误
• 401 Unauthorized - 未登录
• 403 Forbidden - 没权限
• 404 Not Found - 资源不存在
• 500 Internal Server Error - 服务器炸了

用对状态码，前端小伙伴至少能知道发生了什么破事，而不是对着一个200状态码猜半天。

三、命名要说得人话

来看看这些反人类命名：

GET /api/u/list    // u是啥？
POST /api/user/add  // add和create有啥区别？
GET /api/getUserInfo  // RESTful白学了？
POST /api/user/delete  // 删除用POST？

RESTful API的正确打开方式：

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

记住这个口诀：名词复数表示集合，动词用在操作上。别发明创造，老实按规矩来。

四、分页很重要，没商量

「我们的用户接口返回了100万条记录。」

「然后呢？」

「然后前端浏览器崩了。」

这种情况我建议你直接用膝盖想想也知道不行。任何返回集合的接口都必须支持分页。

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

简单粗暴有效。别偷懒，别侥幸，数据量上来有你哭的。

五、错误信息要有营养

最常见的错误返回：

{ "error": "error" }
{ "message": "操作失败" }
{ "msg": "1" }  // 绝了

不是，你倒是告诉我哪儿失败了？让我猜谜呢？

有营养的错误信息应该包含：

{  
  "code": "VALIDATION_ERROR",
  "message": "请求参数验证失败",
  "errors": [
    {
      "field": "email",
      "message": "邮箱格式不正确"
    }
  ]
}

前端一看就知道哪个字段有问题，怎么改。这才叫服务到位。

六、版本号是个好东西

「我们改了个接口参数，前端全炸了。」

「你们为什么不预留版本号？」

「什么是版本号？」

好问题。API是需要演进的，但不能影响老用户。URL版本号是最简单的方案：

/api/v1/users
/api/v2/users

或者请求头版本：

Accept: application/vnd.myapp.v2+json

这样新老用户互不干扰，慢慢迁移岂不美哉？

七、文档是最好的沟通

没有文档的API，就像没有说明书的家电——看着能用，但用起来处处踩雷。

现在工具这么发达，Swagger、OpenAPI、Apifox...随便挑一个。写文档不丢人，丢人的是让人家来问你这个参数是干啥的。

文档里必须有的内容：

• 每个接口的用途
• 请求参数说明（类型、必填、含义）
• 响应格式说明
• 错误码列表
• 示例请求/响应

写在最后

API设计看起来是小事，但细节见真章。一个好的API，能让前后端配合默契，开发效率翻倍；一个烂API，能让整个团队每天都在撕逼中度过。

记住这句话：你写的API是给人用的，不是给你自己看的。多站在调用方的角度想想，很多问题自然就有答案了。

好了，今天的小龙虾课堂就到这里。关注我，带你了解更多程序员那些事儿。

有问题评论区见，别不好意思问。