在 REST API 中选择合适的 HTTP 状态码（实用指南）

Source: Dev.to

在 REST API 中选择正确的 HTTP 状态码听起来很简单——直到你真正参与项目。
在实际工作中，同样的问题不断出现：

• 对验证错误返回 200 OK
• 在 400 与 422 之间混淆
• 401 与 403 交替使用
• 将业务规则失败映射到随意的 4xx 码

这些细微的不一致会逐渐破坏 API 合约，并使前后端协作变得更加困难。

Live Demo

https://ramkumar-kollimalayan.github.io/rest-api-response-code-helper/

GitHub Repository

https://github.com/ramkumar-kollimalayan/rest-api-response-code-helper

Status Code Comparisons

400 vs 422

• 400 Bad Request – 请求格式错误或结构无效。
• 422 Unprocessable Entity – 请求语法正确，但业务验证失败。
  当负载本身没有问题但违反了领域规则时使用 422。

401 vs 403

• 401 Unauthorized – 缺少或无效的身份验证。
• 403 Forbidden – 用户已通过身份验证，但没有权限。
  在构建安全 API 时，这一区别非常重要。

409 Conflict

常见场景：

• 数据重复
• 版本冲突
• 业务规则违规

Visual Helper

在代码评审中一次又一次解释这些选择后，我制作了一个小型可视化助手，将常见的 REST API 场景映射到相应的 HTTP 状态码。

Goals

• 简单胜于完整
• 面向 REST 的使用（而非浏览器行为）
• 明确的“何时使用”指引
• 真实的 API 场景

Observations

让我最惊讶的是，开发者们往往把它当作参考手册而不是一次性阅读的文档。这进一步说明，解决日常困惑的“小而专注”工具往往比庞大、详尽的文档更有价值。

Call for Feedback

如果你经常设计或审查 API，欢迎分享：

• 你看到最常被误用的 HTTP 状态码是哪几个
• 任何你会选择不同状态码的场景

感谢阅读！