## 直接说结论
接口设计就三件事：命名让人秒懂、出错能查原因、改动不坑队友。做好这三点，联调时间砍半。下面全是我踩坑换来的，照着改就能少挨骂。
## 我见过最离谱的接口长这样
刚工作时我写过一个 `/getUserInfoById`，参数叫 `id`，返回里嵌套五层。前端同事调了一下午，最后摔键盘走人。老板让我请他吃饭，那顿饭花了我三百多。
后来我自己接手别人的接口才懂那种痛——字段叫 `data1`、`data2`，文档三个月没更新。你猜怎么着？我直接去翻源码才搞明白它要传什么。
**命名这件事，别偷懒。** 路径用名词复数，`/users` 比 `/getUserList` 干净。动作交给 HTTP 方法去表达，GET 查、POST 建、PUT 全量改、PATCH 局部改、DELETE 删。别在 URL 里写动词，`/deleteUser?id=1` 这种写法，我看一次血压高一次。
## 错误码不是随便编的
有次我图省事，所有错误都返回 `{code: 500, msg: “系统繁忙”}`。结果线上出问题，日志里全是“系统繁忙”，查了两小时才发现是某个参数少传了。
**错误信息要能定位问题，不是拿来糊弄人的。** 我现在坚持三条：HTTP 状态码管传输层，业务错误码管逻辑层，两者别混。比如参数校验失败返回 400，同时 body 里给 `{code: 1001, msg: “手机号格式不对”}`。业务码分段管理，一万号段给用户模块，两万号段给订单，找起来快得多。
还有个细节：**错误信息别暴露内部实现。** 别把 SQL 报错直接甩给前端，写“数据查询失败”就够了，具体原因记服务端日志。
## 版本和兼容，别等出事再想
我吃过最大的亏，是给返回字段改了个名。我觉得改个名而已，结果三个调用方全挂了。半夜爬起来回滚，那滋味真不好受。
**改接口之前，先问自己：调用方会不会挂？** 加字段一般安全，删字段和改类型是红线。非改不可就升版本，`/v2/users`，老版本留半年再下。文档里写清楚废弃时间，别搞突然袭击。
分页参数统一用 `page` 和 `page_size`，别一个接口用 `offset`，另一个用 `start`。返回结构固定成 `{items: [], total: 0, page: 1}`，前端写一次适配就够。时间格式全部 ISO 8601，别一会儿时间戳一会儿字符串，谁接谁崩溃。
## 常见问题
**Q：接口返回要不要包一层 code、msg、data？**
A：要。统一结构方便前端拦截器处理错误，但 HTTP 状态码也要正确设置，别一律返 200。两者配合用，排查问题最快。
**Q：RESTful 和 RPC 风格选哪个？**
A：对外公开接口优先 RESTful，语义清晰好理解。内部高频调用可以 RPC，性能好。别混着用，一个项目一套风格。
**Q：接口文档怎么维护才不烂？**
A：用代码生成文档，别手写。改代码自动同步，手写的文档活不过两周。以官方工具说明为准，选团队顺手的就行。
**Q：参数校验前端做还是后端做？**
A：两边都做。前端为了体验，后端为了安全。后端永远不信前端传来的任何东西，这是底线。
**Q：接口响应慢，先优化哪里？**
A：先加日志看耗时分布，别瞎猜。数据库查询和外部调用通常是瓶颈，加缓存或改批量。别一上来就加机器。
## 写在最后
这些规矩看着琐碎，但每一条背后都是我熬过的夜。你被哪个接口坑得最惨？或者你有什么私藏的接口设计习惯？评论区聊聊，我挑几个有意思的接着写。
📚 相关专题：未分类