API 设计的十宗罪

我对接过大量 API，也设计过一些让自己事后后悔的 API。以下是我总结的”十宗罪”，不限于 REST。

第一罪：返回格式不统一

同一个服务，有的接口返回 { data: ... }，有的直接返回对象，有的返回数组。调用方每次都要猜。

正确做法：定义一个统一的响应结构，全局遵守。

第二罪：错误码语义模糊

{ code: 1001, message: "操作失败" } 这种错误信息，调用方拿到之后能做什么？什么叫”操作失败”？是参数错了还是服务端炸了？

第三罪：用 HTTP 200 返回所有错误

把业务错误包在 200 里面返回，导致调用方没办法用 HTTP 状态码做错误处理，只能每次解析 body。这是最常见、也最烦人的反模式。

第四罪：接口粒度过粗或过细

“把所有用户操作都放在一个 /user/action 接口里，用参数区分”——这种设计看起来简洁，实际上是把路由逻辑下沉到了参数层，导致文档难写、测试难做、权限难控。

反过来，接口拆得太细，一个页面需要发十几个请求，也是灾难。

第五罪：没有分页

返回列表却不分页，在数据量小的时候没问题，数据多了会直接超时或 OOM。

后五宗罪（精简版）

• 第六罪：字段命名风格不统一（userId vs user_id vs UserID）
• 第七罪：时间格式不统一（时间戳 vs ISO8601 vs 中文字符串）
• 第八罪：破坏性变更不做版本控制
• 第九罪：没有幂等性设计（重试会导致重复数据）
• 第十罪：文档和实现不同步（这是所有罪中最普遍的）

好的 API 是给调用方的礼物。烂的 API 是给调用方的诅咒，而且会一直存在。