API设计成垃圾的5个致命错误，我全犯了，你呢？
干后端这些年，我设计过几十个API，有些挺好，有些烂到自己都不想看。有些API刚上线时美滋滋，过了半年就成了技术债务重灾区，前端同学天天在群里阴阳怪气。
今天不整虚的，直接上硬货，说说我犯过哪些致命错误，以及怎么绕过去。文末有总结，照着检查能救一个是一个。
错误一：把所有业务逻辑都塞到一个接口里
早年我设计过一个订单接口，大概长这样：
POST /api/order/create这个接口干了啥？创建订单、扣库存、发送通知、更新用户积分、记录日志、触发某些业务规则判断……一个接口快赶上一个小系统了。
然后有一天，产品说"这个场景下不需要扣库存"，我整个人都裂开了。这个接口根本没法改，牵一发动全身。
正确做法：一个接口只干一件事，复杂业务用编排层组合。CQRS不是银弹，但分离读写确实能救命。把"创建订单"和"扣库存"拆成两个独立动作，通过消息队列或者编排服务协调，灵活度直接翻倍。
错误二：返回数据格式跟掷骰子一样随机
这个是我见过最普遍的烂API特征。同一个接口，有时返回：
{"code": 200, "data": {...}}有时返回：
{"status": "success", "result": {...}}有时直接裸奔：
{...}前端同学每次接数据都要写一堆兼容代码，心里早就把我祖宗十八代问候了一遍。
正确做法：统一响应格式，一个项目自始至终就用一套。推荐结构：
{
"code": 0,
"message": "success",
"data": null
}code用业务错误码，message用于人类可读描述，data才是真正的载荷。约定大于配置，谁乱改格式谁滚去写文档。
错误三：分页实现跟精神分裂似的
先看这三个接口的返回：
// 接口A
{"items": [...], "total": 100, "page": 1, "pageSize": 20}
// 接口B
{"list": [...], "count": 100, "p": 1, "size": 20}
// 接口C
{...} // 直接返回数组，自己数length这是同一个项目的三个接口，我没开玩笑。分页参数也是五花八门，page、p、pageNum、offset、cursor……前端接一个骂一个。
正确做法：统一分页规范，参数和响应都要标准化。我推荐cursor-based分页，性能好，特别适合实时性要求高的场景。简单列表用offset-based也没问题，但必须在文档里明确参数含义。
// 请求
GET /api/users?cursor=xxx&limit=20
// 响应
{
"data": [...],
"next_cursor": "xxx",
"has_more": true
}错误四：HTTP状态码乱用，跟瞎子摸象一样
见过最离谱的API：接口出错时返回200，然后在body里写"status": "error"。我当时就问号脸，HTTP状态码是摆设吗？
还有一些经典乱用：
- 找不到资源返回200（应该404）
- 参数错误返回500（应该400）
- 未授权返回404（应该401）
- 禁止访问返回200（应该403）
这种API调试起来简直是噩梦，日志里全是200，但业务全是错的。
正确做法：老老实实用标准HTTP状态码：
- 200：成功
- 201：创建成功
- 400：参数错误
- 401：未认证
- 403：无权限
- 404：资源不存在
- 422：参数校验失败
- 429：请求过于频繁
- 500：服务端错误（慎用！尽量细化4xx）
状态码是API的"第一语言"，用对了能省一半调试时间。
错误五：不做版本管理，API说改就改
这是最要命的。初期图快，API不带版本号直接上线。半年后要加字段，发现如果加在返回里，现有客户端全崩；如果不加，新需求没法支持。两难。
然后就是灾难：
POST /api/createUser // v1
POST /api/v1/createUser // v2
POST /api/v2/createUser // v3
// 产品：这个字段要去掉
// 我：？？？正确做法：从第一天就做版本控制。URL版本是最直观的方式：
GET /api/v1/users
GET /api/v2/users每个版本的API都要有明确的生命周期：维护期、废弃期、下线期。废弃某个版本前必须给足时间让调用方迁移，至少一个季度。
总结：5条保命清单
不想被前端和调用方追杀的话，对照检查：
- 接口单一职责：一个接口只干一件事，复杂业务靠编排
- 统一响应格式：code、message、data三件套，一个项目用到底
- 标准化分页：参数和响应都要统一，推荐cursor分页
- 正确用HTTP状态码：不要用200表示错误，那是自找麻烦
- 版本管理从第一天做起：v1/v2/v3，宁可多维护也不要改崩存量
API设计是后端的门面，写得好不好直接影响前端对接体验、问题排查效率、后续维护成本。我这些错误都是血泪教训，踩过的坑比走过的路还多。
如果你发现自己中了两条以上，别慌，从今天开始重构一块，慢慢来。API烂不怕，怕的是你知道烂还不改。
有问题的老铁，欢迎评论区吐槽你见过的奇葩API设计，一起避坑。
