干过后端的都知道，API这玩意儿，写的时候敷衍了事，调的时候叫苦连天。今天不整那些虚的，就聊聊我踩过的坑和总结的经验。

1. 命名这关过不了，后面全是灾难

很多人写API命名就跟给变量起名叫 temp、temp2、temp3 一样随意。/getUser、/queryData、/fetchInfo — 你是认真的吗？

RESTful 规范说了，资源用名词，动词由 HTTP 方法提供。但我见过最离谱的接口叫 /doSomething，看名字根本不知道它在干啥。

我的命名规则就三条：

• 名词复数：/users 而不是 /getUser
• 层级清晰：/users/{id}/orders 表示用户的所有订单
• 全局唯一：同一个资源不管在哪，路径都得一样

2. HTTP 状态码不是摆设

见过太多接口永远只返回 200，哪怕出错了也返回 {"error": "something wrong"} 然后 status code 还是 200。这是糊弄谁呢？

状态码就是给调用方的快速判断通道：

• 2xx：成功了，具体啥情况
• 4xx：你客户端的锅，我没毛病
• 5xx：我服务器抽风了，跟你无关

最常用的几个：200 OK、201 Created、400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、500 Internal Server Error。这些必须用对，用准。

3. 分页不做，大数据必崩

"没事儿，我们数据量不大" — 说这话的后来都哭着来找我优化了。

数据量是会长的好吗！分页是后端基本素养：

GET /users?page=1&page_size=20

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

cursor 分页和 offset 分页各有适用场景：数据需要实时更新用 cursor，不要求严格一致用 offset。别傻傻分不清。

4. 统一响应格式，省心一辈子

有的接口返回 {"code": 0, "data": ...}，有的返回 {...}，有的返回 [[],[]]。每次调接口还得猜格式，心累。

统一格式规范：

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

// 出错时
{
  "code": 40001,
  "message": "用户不存在",
  "data": null
}

code 用业务错误码，message 给人类看，data 装实际数据。接口文档写清楚了，大家都不累。

5. 幂等性：这事儿搞不清楚迟早翻车

POST 请求调两次会创建两条数据？还是只执行一次？GET 是天然幂等的，这个没争议。但 POST、PUT、PATCH、DELETE 你真搞清楚了吗？

• POST：非幂等，每次调用都创建新资源
• PUT：幂等，全量替换同一个资源
• PATCH：非幂等，部分更新
• DELETE：幂等，删一次和删一百次效果一样

支付这类接口必须保证幂等，不然用户多扣一次钱你就等着被祭天吧。

6. 版本管理：不要等到无法挽回

"先上线再说，后面再重构" — 这是我听过最贵的谎话。

接口版本必须一开始就规划好：

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

新版本兼容老版本至少一个版本周期，给调用方留足迁移时间。老版本下线前一个月发通知，别搞突然袭击。

最后说两句

写 API 这事儿，技术含量不高，但讲究多。命名规范、状态码正确、响应统一、幂等保证、版本管理——都是老生常谈，但能真正做好的不多。

原因很简单：这些坑不踩过，你永远不知道有多疼。别人踩过的，你看了也不当回事儿。

所以，我的建议是：找个不重要的接口，故意踩踩坑，感受一下什么叫"出来混迟早要还的"。等你被线上问题折腾过，就会明白这些规范的好了。

祝你的 API 稳如老狗，别半夜被电话叫醒。 🦞