为什么你的API总被吐槽？这份避坑指南让你少走三年弯路

干后端开发的，谁还没被前端追杀过几条街？接口返回格式乱糟糟，状态码随心所欲，文档写得像遗书——这些都是家常便饭。今天咱们就聊聊那些年我们一起踩过的API设计坑，以及怎么优雅地爬出来。

一、状态码不是万能药，别把它当处方开

很多教程上来就告诉你：200成功，400客户端错误，500服务端错误。背得滚瓜烂熟，一写代码就抓瞎。

我见过最离谱的一个接口：用户注册时邮箱格式不对，返回200，加个code字段标注"邮箱格式错误"。前端收到200，开开心心告诉用户"注册成功，请去邮箱激活"。然后用户打电话投诉说网站有bug。

状态码是用来表达HTTP层面的语义，不是用来替代业务状态码的。你的业务逻辑错误，该403就403，该422就422，别为了"统一"把200当成万能成功码。

记住：HTTP状态码是给网络设备和中间件看的，你的业务状态码才是给前端程序员看的。两个东西，各司其职。

二、URL设计的第一原则：别说人话，先说清楚能做啥

见过最骚的API设计：/api/v1/user/123/action/execute。请问这是要删除用户还是更新用户？鬼知道。

好的URL应该像一扇门的标签，推开门就知道里面有什么。

# 好的设计
GET /users/:id                    # 获取用户
POST /users                       # 创建用户
PUT /users/:id                    # 更新用户
DELETE /users/:id                # 删除用户

# 差点意思的设计
GET /getUserById?id=123
POST /createNewUser
POST /updateUserInfo
POST /deleteUser

# 离谱的设计
GET /user/123/data/fetch
POST /user/123/action/execute

RESTful的精髓不是把名词复数化，是让你看URL就能猜出这条接口能干什么。如果你的URL需要用注释解释，那它就不是好的设计。

三、返回格式的黄金定律：一致性比"正确"更重要

有些程序员喜欢标新立异：成功时返回数据，失败时返回错误信息。这是正确的，但它是灾难的开始。

// 今天这样
{"code": 200, "data": {"name": "张三"}, "message": "操作成功"}

// 明天又那样
{"status": "ok", "result": {"name": "张三"}}

// 后天突然开窍了
{"success": true, "payload": {"name": "张三"}}

前端程序员面对这种接口，要么写一堆if-else兼容处理，要么直接骂街。他们没骂出来的那个词，大概是"祖宗"。

统一响应格式不需要多复杂，一个data一个code够了。但格式一旦定下来，全项目谁都不许改。改格式是重大版本升级，要发通知的那种。

最可怕的不是返回格式丑，是返回格式不一致。今天项目A能跑，明天接手项目B就爆炸。程序员的时间都去哪了？都去兼容这些破格式了。

四、分页不是简单Limit+Offset就完事了

最常见的分页实现：GET /users?page=1&limit=20，返回20条记录，前端自己算总数。

然后产品经理问：为什么用户列表翻到第五页就少了两条记录？

因为在你翻页的过程中，有人在删用户。经典的分页幻读问题。数据量小的时候无所谓，数据量大了翻车翻到你怀疑人生。

解决方案：用游标分页（Cursor Pagination）。不要数第几条，要记住"最后一条的ID是什么"。这样新增删除都不影响你的分页位置。

// 传统偏移分页（有问题）
GET /users?page=3&limit=20
// 总数500，第60条到第80条

// 游标分页（靠谱）
GET /users?limit=20&cursor=eyJpZCI6NjB9
// 返回 {"data": [...], "next_cursor": "eyJpZCI6ODB9", "has_more": true}

当然，游标分页不适合"跳转到第10页"这种需求。但实际上，用户真正需要跳转到第几页的场景，少得可怜。大多数场景下，"加载更多"就够了。

五、错误信息是API的门面，不是附赠品

很多程序员的错误处理是这样的：

// 要么什么都不返回
return res.status(500).send()

// 要么返回奇怪的东西
return res.status(400).send("出错了")

// 更离谱的
return res.status(200).json({ error: "参数错误" })

错误信息的黄金法则：让调用方知道错在哪、怎么修、有没有记录可供排查。

{
  "code": 400,
  "error": {
    "message": "邮箱格式不正确",
    "field": "email",
    "rejected_value": "user@",
    "reason": "缺少域名部分，正确格式示例：user@example.com"
  },
  "request_id": "req_abc123xyz"
}

这个error对象里，message是人话，field告诉前端哪个字段出错了，rejected_value让前端能回填用户刚才输入的内容，reason是给用户看的解释，request_id是用来查日志的。

你多写两行代码，排查问题少花两小时。值不值？

六、版本控制不是为了卷，是为了活下去

很多人不重视API版本控制，上来就是/api/users，然后业务变了要改接口，改着改着就把老接口搞坏了。

版本控制的三种流派：

// URL路径版本（直观但不够RESTful）
GET /api/v1/users
GET /api/v2/users

// Header版本（标准但容易被忽略）
GET /users
Accept: application/vnd.myapp.v1+json

// Query参数版本（简单但不推荐）
GET /users?version=1

我的建议：小项目用URL路径版本，大项目用Header版本。Query参数版本是懒人偷懒用的，长期维护会哭。

版本控制的核心是：旧版本要能活足够久，让所有调用方有时间迁移。一般给3-6个月的过渡期比较合理。急着下线老接口而不给迁移时间的，都是在给同事挖坑。

七、幂等性：这个概念能救命

什么是幂等性？一个操作执行一次和执行多次，结果是一样的。

GET请求天然幂等，DELETE也幂等（删两次和删一次结果一样）。但POST和PATCH呢？

举个真实的例子：用户点支付按钮，手抖点了两次。扣了两次钱，客诉电话被打爆。

解决方案：接口要设计成幂等的。支付这种操作，用唯一的订单号作为幂等键。

POST /payments
{
  "order_id": "ORDER_20260430_001",
  "amount": 100,
  "idempotency_key": "user123_payment_once"
}

后端记录这个idempotency_key，如果同一个key请求两次，直接返回第一次的结果。用户在页面上等了三秒，你告诉他"支付成功"，后台其实查了一下缓存而已。省了多少事？

幂等性设计不是在修复bug，是在预防bug。别等线上出事了再想起来加。

八、安全是底线，别拿"内部接口"当借口

我听过最可怕的话："这个接口是内部用的，不加鉴权也没关系。"

然后呢？然后这个接口被人扫到了，数据泄露了，背锅的是谁？还是写"内部接口不用鉴权"的那个人。

API安全的基本要求：认证要加、权限要控、输入要校验、敏感数据要脱敏。这四条不是可选项，是必选项。

// 所有对外接口，认证是默认项
// 不要问"要不要加认证"，要问"这个接口谁能访问"

// 认证+授权分离
GET /admin/users  # 需要admin角色
GET /users        # 需要登录状态

// 敏感数据脱敏
{
  "phone": "188****7618",
  "id_card": "410***********1234"
}

安全这事，永远不要心存侥幸。墨菲定律说了：只要有可能出问题，就一定会出问题。

写在最后

好的API设计不只是"能用"，是"好用、易维护、不踩坑"。很多人觉得这些是纸上谈兵，但你真正踩过一次分页幻读、经历过接口破坏性升级、排查过状态码混乱的线上问题，就知道这些原则值多少个加班夜。

代码是给机器读的，也是给同事读的。留一份好读的接口文档，少一份被追杀的恐惧。祝各位的接口都顺顺利利，少挨几顿骂。