- 约1503字
- 技术
- 2026年4月2日
每次接口返回格式不一样，前端解析到崩溃；某个字段悄悄改名后端没通知，全站炸了；错误码乱七八槽，运维排查问题无从下手——这些场景是不是很眼熟？
我带过的项目里，至少有80%出现过以上问题。API设计看似简单，但真正做好的人不多。今天把这9个最常见的错误列出来，帮你一次性绕过这些坑。
错误一：返回格式不统一
同一个项目里，有的接口返回 {code: 200, data: {...}}，有的返回 {status: "ok", result: {...}}，还有的直接返回数组。
前端同学每次对接新接口都要问：「这个接口怎么解析？」
正确做法：整个项目统一返回格式。最推荐的是标准的 {code, data, message} 结构：
{
"code": 200,
"data": {...},
"message": "success"
}
其中 code 用数字表示业务状态码，message 给用户看，data 才是真正的业务数据。
错误二：没有版本号
接口直接挂在 /api/users、/api/orders，没有任何版本标识。某天后端改了个字段名，旧版客户端全部报错。
正确做法：URL中加入版本号 /api/v1/users、/api/v2/users。向后兼容的原则是：新版本能响应的内容，旧版本客户端也能正常解析。
错误三：HTTP方法乱用
有人把 GET 请求用来做数据变更，或者在一个 POST 请求里同时做增删改查。看起来省事了，后续维护和调试全是坑。
正确做法：
- GET：查询
- POST：新增
- PUT：全量更新
- PATCH：部分更新
- DELETE：删除
别偷懒，方法选对了，日志排查和权限控制都会简单很多。
错误四：分页参数不一致
同样是分页，有的接口用 page+pageSize，有的用 offset+limit，有的用 start+count。一个项目里三四种写法，前端要写三套逻辑。
正确做法：整个项目统一分页参数，推荐 page+pageSize（页码+每页数量），直观且符合用户习惯。返回时记得带上 total 和 hasMore 字段。
错误五：错误信息没有标准
错误响应有的返回 {error: "用户不存在"}，有的返回 {code: 404, msg: "not found"}，还有的直接返回 500 加一段堆栈信息。
正确做法：建立统一的错误码体系。建议区分「业务错误」和「系统错误」：
// 业务错误（4开头）
{ "code": 4001, "message": "用户名已存在" }
// 系统错误（5开头）
{ "code": 5001, "message": "服务暂不可用" }
前端可以根据错误码做统一的错误提示和重试逻辑。
错误六：字段命名不规范
有的接口用 userId，有的用 user_id，还有的用 userId、uid 混用。JSON 本身的蛇式/驼峰不是问题，问题是同一个项目里不统一。
正确做法：要么全项目驼峰，要么全项目蛇式。最重要是团队约定、文档统一、代码审查时检查。
错误七：没有说明文档
接口做好了扔给前端：「自己看吧。」没有文档，没有示例，没有变更记录。
正确做法：用 Swagger / OpenAPI 文档自动生成。接口变更时及时更新文档，并在群里通知前端负责人。文档是最好的沟通方式，比口头交接靠谱一百倍。
错误八：敏感数据明文返回
用户密码、手机号、身份证号直接放在返回结果里。前端显示没问题，但这就是一个安全炸弹。
正确做法：后端返回脱敏数据，或标记哪些字段需要前端二次处理。密码字段永远不要返回。
错误九：没有做幂等设计
重复点击「提交」按钮，订单创建了两条；刷新页面，表单数据被重复提交。这些问题不是前端的事，是后端没有做幂等。
正确做法：对于写操作接口，用唯一标识符（订单号、token）保证幂等性。POST 请求可以用「创建并返回」或「如果存在则返回」两种策略。
API 设计做得好不好，不是看你的接口多规范，而是看前端对接时省不省心。上面的9个错误里，哪怕只做到一半，你的接口质量也已经超过大多数项目了。
前端工程师最怕的不是接口多，而是「同一个项目的接口像不同人写的」。把规范定下来，按规则执行，联调的摩擦能少一半。