电脑工场
白蓝主题五 · 清爽阅读
首页  > 软件入门

API设计中状态码怎么用才不翻车?

写接口时随手扔个 200 OK,前端同学抓着头发问:‘这算成功还是失败?’——状态码不是凑数的装饰品,是前后端沟通的暗号。

4xx 和 5xx 不是随便挑的

比如用户登录填错密码,后端返回 500 Internal Server Error,前端以为服务器崩了,其实只是账号密码不对。正确做法是 401 Unauthorized(未认证)或 403 Forbidden(已认证但无权限),让调用方一眼看懂问题在哪。

再比如删除一个根本不存在的订单,有人图省事直接返回 200 并附一句 {"msg": "删除成功"}。这会让前端误判操作成功,实际啥都没删。应该返回 404 Not Found,明确告诉:你要删的东西,压根不在系统里。

2xx 的分工要清楚

200 是最常用,但不代表万能。创建资源(比如新增一条评论)成功后,更规范的响应是 201 Created,并在响应头里带上 Location:

HTTP/1.1 201 Created\nLocation: /api/comments/123
这样前端就知道新资源的地址,不用再手动拼接 ID。

而执行完一个无返回值的操作(比如点赞、静音某用户),204 No Content 更合适——既表示成功,又说明不用解析响应体,省流量也省解析逻辑。

别自创状态码

有人觉得 418 I'm a teapot(我是个茶壶)很有趣,真在生产环境用了,前端同事可能真的去泡茶。RFC 标准里定义的状态码已经覆盖绝大多数场景,非要扩展,优先用 400 Bad Request + 响应体里的 code 字段说明具体错误类型,比如:

{\n  "code": "INVALID_PHONE_FORMAT",\n  "message": "手机号格式不正确"\n}
比硬塞个 499 或 422 更易维护。

状态码不是技术炫技,是降低协作成本的最小单位。你多想一秒怎么返回,别人就少查十分钟日志。