## 直接说结论
API 设计规范的核心就三件事：命名统一、错误可读、版本可控。把这三样做到位，前后端联调能省一半扯皮时间。别追求大而全的规范文档，先落地这三点比什么都强。
## 命名这事，我被骂过三次
刚工作那会儿，我设计的第一个接口叫 `/getUserInfo`，同事看了一眼说：“你这动词放前面，是认真的吗？”
后来我改成 `/user/info`，又被吐槽说 info 太模糊，到底是基础信息还是详细信息？最后定成 `/users/{id}/profile`，才算消停。这件事让我明白，命名不是自己看着顺眼就行，得让调用方一眼看懂资源关系。
我的经验是：路径用名词复数，层级表达从属关系，动词交给 HTTP 方法去表达。`GET /orders/{id}/items` 比 `/getOrderItems` 清楚得多。查询参数用 `?status=paid&page=2` 这种扁平结构，别搞嵌套三层以上，否则调试时眼睛都花了。字段名统一用 snake_case 还是 camelCase 都行，关键是整个项目别混着来，我见过一个接口返回里两种风格同时存在的，那酸爽。
## 错误码别只丢一个 500
有次线上出问题，前端同事截图给我看，接口返回 `{“code”: 500, “msg”: “系统繁忙”}`。我问他具体什么操作触发的，他说不知道，因为所有错误长得一模一样。
那次之后我改了策略：业务错误码分段管理，比如 1xxxx 是用户模块，2xxxx 是订单模块。HTTP 状态码该用 400 就用 400，该用 404 就用 404，别全塞 200 里再靠 body 判断。错误响应体里带上 `request_id`，排查问题时拿这个 ID 去日志系统一搜，链路清清楚楚。
还有一点，错误信息别写“参数错误”这种废话。写成“字段 `mobile` 格式不正确，应为 11 位数字”，前端拿到就能直接弹给用户看。
## 版本控制，越早做越省事
我吃过最大的亏，是在一个已经上线半年的项目里改返回结构。把 `user_name` 改成 `username`，觉得反正就一个字段。结果有个老客户端没更新，直接白屏。
后来学乖了：URL 里带版本号，`/v1/users` 和 `/v2/users` 可以并存。新版本改结构，老版本继续跑，给调用方留足迁移时间。别信“我们内部系统不用版本”，只要有人调你的接口，就得考虑兼容。兼容策略也简单：加字段可以，删字段和改类型必须开新版本。以官方说明为准这句话放在这里也适用——文档写清楚每个版本的生命周期，比口头承诺靠谱。
## 文档和示例，比规范本身重要
我见过太多团队花两周写规范文档，然后没人看。问题出在文档里全是“应该”“建议”，没有能直接跑的示例。
我的做法是：每个接口配一个 curl 示例，请求参数和响应字段都标上类型和是否必填。再懒一点，用 OpenAPI 描述文件自动生成文档，改代码时顺手更新描述，比单独维护一份 Word 强。联调时前端直接照着示例构造请求，有问题先看文档，减少一半“这个字段什么意思”的提问。
## 常见问题
**Q：接口返回时间格式用时间戳还是字符串？**
A：推荐 ISO 8601 字符串，比如 `2024-01-15T10:30:00+08:00`。时间戳可读性差，跨时区还容易算错，字符串格式前端直接能解析，调试也直观。
**Q：分页参数用 offset 还是 cursor？**
A：数据量小用 offset，简单直接；数据量大或实时性高用 cursor，避免翻页时数据重复或遗漏。具体选哪个看业务场景，没有绝对标准。
**Q：PUT 和 PATCH 到底怎么选？**
A：PUT 是全量替换，PATCH 是局部更新。如果只想改一个字段，用 PATCH 更合适，但实际项目里很多团队直接用 POST 加动作路径，也能跑，关键是团队内部说清楚。
**Q：接口超时时间设多少合适？**
A：普通查询 3 到 5 秒，复杂导出或批量操作单独设长超时并走异步。别所有接口一个超时值，容易把慢接口拖死。
**Q：要不要做接口幂等？**
A：涉及支付、下单、扣库存这类操作必须做。用唯一请求 ID 或业务单号去重，防止用户连点两下产生两笔订单。
## 写在最后
规范这东西，写出来容易，落地难。你们团队现在用的接口规范里，哪一条是踩过坑之后才加上的？有没有那种“明明写了但没人遵守”的规定？评论区聊聊，我看看是不是大家都一样。
📚 相关专题：未分类