## 直接说结论
接口设计就三件事：命名让人看懂，参数别太随意，错误码说人话。做到这三点，前端不骂你，联调少加班，文档不用追着更新。下面全是我踩坑换来的。
## 命名这事，别秀技术
刚工作时我设计过一个接口叫 `/getUserInfoById`，自我感觉清晰。结果前端同事问我：“批量查怎么命名？`getUserInfoByIds`？那按手机号查呢？”我当场愣住。
后来学乖了，资源用名词复数，动作交给 HTTP 方法。查用户就是 `GET /users`，查单个 `GET /users/{id}`，批量传 `ids` 参数。别在 URL 里塞动词，`/getUser`、`/queryUser`、`/fetchUser` 这种词，团队里三个人能写出三种拼法。
还有一个坑：大小写和连字符。我见过 `/userInfo` 和 `/user-info` 混用的项目，前端拼 URL 全靠猜。统一用短横线或下划线，选一个就别改。以团队规范为准，但一定要写进文档。
## 分页、筛选、排序，一次说清
分页参数最容易被忽略。早期我设计成 `page` 和 `size`，结果有人传 `page=0`，有人传 `page=1`，还有传 `offset` 的。后来统一成 `page` 从 1 开始，`page_size` 默认 20，最大 100。想跳页用 `offset` 也行，但别混着来。
筛选参数我犯过更大的错。一开始让前端传 `filter={“name”:”张三”,”age”:18}` 这种 JSON 字符串，结果 URL 编码各种翻车，中文、特殊字符全乱套。改成扁平参数 `name=张三&age=18`，简单直接。多个值就 `status=active,pending`，逗号分隔，别嵌套。
排序用 `sort=-created_at`，前面加负号表示倒序。这个规则我抄的，但真好用。前端一看就懂，不用猜 `order=desc` 还是 `sort_type=desc`。
## 错误码，别让前端猜谜
最崩溃的一次：接口返回 `{“code”: 500, “msg”: “系统错误”}`，前端问我哪错了，我只能去翻日志。后来定规矩：业务错误码用 4 位数字，前两位对应 HTTP 状态，后两位细分。比如 `40001` 参数缺失，`40002` 参数格式错，`40101` token 过期。
HTTP 状态码也别浪费。参数错就 400，没登录就 401，没权限就 403，找不到就 404。别所有错误都返 200，然后在 body 里写 `success: false`。我见过这种设计，前端每个接口都要判断两层，烦死。
错误信息要给人看。`“参数错误”` 不如 `“page_size 不能超过 100”`。再进一步，把出错的字段名带上：`“字段 email 格式不正确”`。前端能直接弹提示，不用再查文档。
## 版本和兼容，别拍脑袋
接口一上线就有历史包袱。我试过在 URL 里加 `/v2/users`，结果两个版本并行维护，改一个 bug 要改两遍。后来学聪明了：小改动加可选参数，默认保持旧行为；大改动才升版本，而且旧版本定好下线时间，提前通知。
字段只增不减。想删字段？先标记废弃，文档写清楚，等两个迭代再删。想改字段类型？加新字段，旧字段保留但不再返回数据。别直接改，线上出过事故，半夜被叫起来修。
## 常见问题
**Q：接口返回时间用时间戳还是字符串？**
A：推荐 ISO 8601 字符串，比如 `2025-01-15T10:30:00+08:00`。时间戳虽然小，但前端要自己转时区，容易错。以官方说明为准，选一个全项目统一。
**Q：POST 和 PUT 到底怎么选？**
A：POST 用来创建，PUT 用来全量更新。部分更新用 PATCH。别用 POST 干所有事，语义清晰点，别人看接口名就知道干啥。
**Q：需要返回全量数据吗？**
A：别。列表接口默认只返回必要字段，详细字段单独查。我见过返回用户列表带 50 个字段的，流量白烧，前端还嫌慢。
**Q：接口文档怎么维护？**
A：代码注释生成文档，别手写。手写的迟早和代码不一致。用 Swagger 或类似工具，改代码自动更新，省得扯皮。
**Q：错误码要全局唯一吗？**
A：不用，但同一个服务内要唯一。不同服务可以重复，但要在文档里写清楚。我试过全局唯一，维护成本太高，后来放弃了。
## 写在最后
这些规范不是死的，团队小就少定几条，团队大就写细点。关键是别让前端猜，别让联调变吵架。你有没有遇到过特别离谱的接口设计？评论区聊聊，让我也开开眼。
📚 相关专题：未分类