HTTP Status Codes and Errors

HTTP 状态码是 REST API 设计的重要组成部分。它们用于表达请求结果，让 API 消费者能够正确处理成功响应、客户端错误和服务端错误。

API 应始终使用标准 HTTP 语义，避免暴露与具体实现相关的细节。

定义成功响应和错误响应

API Specification 必须定义成功响应和服务专属的错误响应。

成功响应和错误响应都是 API 契约的一部分。它们说明客户端应如何调用 API，以及如何处理异常情况。

不过，API 不应记录每一种可能的技术错误，尤其是由服务无法控制的基础设施组件引起的错误。

API 应重点记录：

• 与业务相关的错误
• 客户端可以采取不同处理方式的错误
• 需要在 HTTP 状态码之外补充解释的错误

错误响应可以使用 RFC 7807 的 Problem Details 格式，并通过 application/problem+json 返回详细信息。

使用标准 HTTP 状态码

API 必须按照标准语义使用 HTTP 状态码，不得创建自定义 HTTP 状态码。

使用标准状态码可以提升互操作性，避免 API 消费者产生歧义。

成功状态码

重定向状态码

客户端错误状态码

客户端错误表示请求因为输入无效、身份认证、权限控制或请求冲突而无法完成。

服务端错误状态码

服务端错误表示服务在处理一个有效请求时发生了失败。

使用最具体的 HTTP 状态码

API 应始终返回能够准确描述请求结果的最具体 HTTP 状态码。

如果存在更具体的状态码，应避免使用笼统的 400 或 500。

例如，用户已经存在时，创建用户请求应返回：

HTTP/1.1 409 Conflict

而不是返回笼统的 400 Bad Request。

批量请求和批处理响应

批量操作可能包含多个相互独立的操作。由于单个 HTTP 响应码无法表达多个结果，当各个操作产生不同结果时，应使用：

207 Multi-Status

规则：

• 如果需要报告每个独立操作的结果，批量请求应返回 207。
• 响应体必须包含每个独立操作的状态信息。
• 只有当请求在独立处理开始前就失败，或发生意外的全局失败时，才应返回 4xx 或 5xx。

示例：

{
  "results": [
    {
      "id": "123",
      "status": 200
    },
    {
      "id": "456",
      "status": 404,
      "detail": "Resource not found"
    }
  ]
}

使用 Problem JSON 对象

API 应使用 RFC 7807 Problem Details 格式返回错误响应。

媒体类型：

application/problem+json

Problem 响应提供 HTTP 状态码之外的额外信息，通常包含问题类型、标题、状态、详细说明和具体发生位置。

示例响应：

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "type": "/problems/service-unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "The dependent service is temporarily unavailable.",
  "instance": "/requests/abc123"
}

不要暴露堆栈信息

API 绝不能在响应中暴露堆栈信息。

堆栈信息可能：

• 泄露内部实现细节
• 暴露敏感信息
• 造成安全风险
• 诱使客户端依赖具体实现行为

应返回以下内容：

• 标准 HTTP 状态码
• Problem JSON 对象
• 对客户端安全的错误描述

避免：

{
  "error": "NullReferenceException",
  "stackTrace": "at Service.UserHandler.Process()..."
}

推荐：

{
  "type": "/problems/internal-error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred."
}

总结

良好的 REST API 应：

• 在 API Specification 中定义成功响应和错误响应。
• 只使用标准 HTTP 状态码。
• 选择可用的最具体状态码。
• 对需要报告独立结果的批量操作使用 207 Multi-Status。
• 使用 application/problem+json 返回详细错误信息。
• 绝不暴露堆栈信息或内部实现细节。