API设计避坑指南：那些让前端想打人的操作

你知道作为后端写API，最难的部分是什么吗？不是写代码，是不要犯蠢。

我见过太多糟糕的API设计了。有的返回200状态码但里面是个错误；有的时间字段存成字符串导致时区混乱；有的分页参数叫pageSize却要求传page_size。这些问题看似小，但每天都在折磨前端同事。

今天我要认真吐槽一下，顺便给你一份避坑指南。

坑一：HTTP状态码？那是个摆设

我见过最离谱的API，所有的响应都返回200，包括删除失败、登录失败、服务器报错。状态码？不存在的。前端只能解析response里的code字段来判断是不是真的成功了。

拜托，HTTP状态码是干嘛用的？就是让你区分成功和失败的啊！

正确姿势：

• 2xx：一切OK
• 4xx：你客户端的错（参数不对、没权限、找不到）
• 5xx：服务器挂了你别来找我

POST创建资源成功？201 Created + Location头。DELETE成功？204 No Content。这些都是标配，别省。

坑二：分页参数，我怀疑你在故意整我

有的API用page，有的用offset，有的用cursor。参数名也是随机发挥：page、pageSize、page_size、size、limit、count、per_page。还有的更绝，分页响应里根本不带总数和页码，前端只能靠猜。

我强烈建议团队内部统一分页规范：

GET /users?page=1&page_size=20

响应带上元数据：

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

这样前端心里有底，知道还能查多少页，不用瞎猜。

坑三：错误响应格式？随缘吧

同一个系统里，有的接口返回{msg: "error"}，有的返回{message: "错误"}，有的返回{error: "something wrong"}。错误码也是百花齐放：-1、1000、INVALID_PARAMETER、"ERR_001"。

前端工程师：好的，我统一处理一下。
一个月后：后端接口又改格式了。

建议的标准化错误响应：

{
  "code": 40000,
  "message": "参数错误",
  "details": [
    {"field": "email", "reason": "邮箱格式不正确"}
  ]
}

有code方便前端判断类型，有message给人看，有details给排查用。统一格式真的能省很多沟通成本。

坑四：ID设计，一言难尽

很多老系统用自增ID，这意味着什么？意味着我只要调个接口就能遍历你所有的数据。订单ID、用户ID、交易ID，全都能猜出来。

对外暴露的API，请用UUID或者nanoid。虽然长一点，但安全。内部接口性能要求高的，可以用雪花ID。

坑五：字段命名，随机播放

userId、uid、user_id三个字段同时存在于不同接口里。created_at、create_time、createAt、createDate随便挑。updated_by、modifier、last_edit_by，你猜哪个是哪个。

团队内部必须制定命名规范并且严格执行：

• 统一用驼峰还是下划线？选一个，贯穿所有接口
• 时间字段统一用xxx_at格式
• 创建人统一用xxx_by格式

前端对接的时候最怕的就是这种不确定性，每个接口都要重新确认一遍字段名，开发效率就是这么拉低的。

坑六：响应不稳定，玄学调试

有的接口返回的字段时有时无，今天有created_at，明天就没了。有的字段类型飘忽不定，status字段有时是字符串"active"，有时是数字1，前端根本没法做类型判断。

稳定性是API的基本要求。如果字段可能不存在，用nullable；如果字段类型可能变化，文档写清楚。前端最怕的不是字段没有，而是字段有时候有有时候没有，调试到怀疑人生。

坑七：HTTP方法乱用，GET带body你认真的？

见过用GET请求传body的，见过更新操作用POST的，还见过删资源用GET的。问就是"这样也行啊"。

RESTful规范不是摆设：

• GET：查
• POST：增
• PUT：更新（全量）
• PATCH：更新（部分）
• DELETE：删

别为了省事儿就把这些乱来，前端SDK、HTTP客户端、缓存系统都会因为这个出问题。

坑八：没有版本控制，一升级全链路崩塌

有些API压根没有版本的概念，改个字段名就是breaking change，所有调用方都得跟着改。更夸张的是有的API连文档都没有，前端只能靠抓包来猜字段含义。

建议：URL里带版本号，如/api/v1/users。重要变更有版本迭代，给调用方留迁移时间。文档是API的门面，别省。

总结一下

API设计烂，迟早要还的。前端每次对接都是一次修行，调试的时候会想把后端揪出来打一顿。

好的API设计需要站在调用方的角度思考：响应结构清晰、状态码正确、错误信息有用、分页规范、文档完善。这些看起来都是小事，但直接决定了开发体验和协作效率。

说到底，API也是一种用户体验。用户是前端工程师，你的目标是让他们半夜不用爬起来排查问题。

这不是技术问题，是人品问题。