在 REST 风格 API 设计中，响应状态应直接使用 HTTP 标准状态码作为核心语义载体，而不是仅在响应体中自定义业务码。HTTP 状态码是 API 契约的一部分，用于准确传达请求的宏观结果、业务状态或系统异常。

以下是规范的定义方法、典型映射表及最佳实践参考：

📦 一、HTTP 状态码分类与 REST 语义定义

根据 RFC 规范，状态码分为 5 个类别，在 REST API 中应这样理解与使用：

📊 二、典型场景状态码对照表（可直接参考）

💡 注意：避免所有请求都返回 200，再通过 JSON 中的 code 判断成败。这会破坏 HTTP 协议语义，导致网关监控、SDK 自动重试、熔断器等基础设施失效。

🛠 三、REST 响应状态设计规范

1. 状态码表达宏观结果，响应体补充微观信息
   HTTP 状态码负责路由处理分支（成功/客户端错/服务端错），响应体负责传递业务细节。例如 400 可返回：

   { "error": "VALIDATION_FAILED", "message": "手机号格式不正确", "field": "phone" }
   

2. 幂等性需与状态码保持一致
   GET、PUT、DELETE 应为幂等。例如重复调用 DELETE /users/123，第二次可返回 404 或 200，但团队内需统一约定。

3. 工业界常见混合模式（可选）
   为兼容前端统一拦截或国际化提示，许多团队采用 HTTP 状态码 + JSON 业务码信封：

   // 成功
   { "code": 0, "msg": "success", "data": { "id": 1, "name": "tom" } }
   // 失败（HTTP 状态码仍为 400）
   { "code": 1001, "msg": "手机号已存在", "data": null }
   

   此时 HTTP 状态码仍应严格按上述规范返回，内部 code 仅用于业务层路由或前端提示映射。

4. 错误响应体建议结构

   {
     "code": "RESOURCE_CONFLICT",
     "message": "该手机号已被注册",
     "requestId": "req_8f3a2c1d",
     "details": { "field": "phone", "value": "13800138000" }
   }
   

📚 四、权威参考标准

✅ 总结

REST API 的响应状态不需要自定义发明，应严格遵循 HTTP 标准状态码语义：

• 2xx 表示成功，按操作类型细分（查询/创建/更新/删除）
• 4xx 指向客户端问题（参数/权限/资源/业务冲突）
• 5xx 指向服务端问题（异常/依赖/维护）
• 响应体配合状态码提供可调试的业务细节，必要时可叠加内部业务码信封。