2. HTTP 状态码回顾：2xx/3xx/4xx/5xx 系列语义与最佳实践

HTTP 状态码是服务端向客户端（浏览器、移动端、API 网关）传递请求处理结果的标准化信号。在微服务架构与 OpenAPI 契约测试中，状态码不仅是协议层面的约定，更是错误码断言与合规审计的基石。错误的语义映射会导致客户端异常处理失效、监控告警误报，甚至安全漏洞。

2.1 状态码分类总览

RFC 7231 将 HTTP 状态码划分为五大类，每一类代表不同的响应语义层级。后端 API 设计必须严格遵循分类边界，避免将业务异常映射到错误的系列。

2.2 2xx 成功系列详解

2xx 系列表示请求已被成功接收、理解并接受。后端 API 中最常用的三个状态码如下：

• 200 OK — 标准成功响应。用于 GET 查询、PUT 更新、部分 POST 操作。响应体应包含完整的业务数据。
• 201 Created — 资源创建成功。用于 POST 创建资源。响应头必须包含 Location 字段指向新资源 URI。
• 204 No Content — 操作成功但无返回体。用于 DELETE 删除、部分幂等更新。响应体必须为空，禁止返回 null 或空 JSON。

// 201 Created 示例响应
HTTP/1.1 201 Created
Location: /api/v2/orders/ord-20250301-001
Content-Type: application/json

{
  "orderId": "ord-20250301-001",
  "status": "pending",
  "createdAt": "2025-03-01T10:30:00Z"
}

2.3 3xx 重定向系列与 REST 约束

3xx 系列在 REST API 中应谨慎使用。浏览器自动跟随重定向的行为在 API 客户端中可能引发安全问题或状态丢失。

2.4 4xx 客户端错误系列 — 错误码断言的核心战场

4xx 系列是后端安全合规错误码断言最密集的区域。每一个 4xx 响应都必须附带结构化的错误体，帮助客户端精确识别问题。

• 400 Bad Request — 通用请求错误。参数格式错误、缺少必填字段、JSON 解析失败。必须返回错误字段定位。
• 401 Unauthorized — 未认证。缺少 Token、Token 过期、认证头格式错误。响应头应包含 WWW-Authenticate。
• 403 Forbidden — 已认证但无权限。角色不足、资源隔离、IP 白名单拒绝。不应暴露具体权限细节。
• 404 Not Found — 资源不存在。URI 错误、资源已删除。注意：不要返回 404 来隐藏敏感资源是否存在（安全考虑）。
• 409 Conflict — 资源冲突。重复创建、版本冲突、唯一约束违反。应返回冲突的字段标识。
• 422 Unprocessable Entity — 语义错误。业务规则校验失败、状态机不允许的操作。比 400 更精确。
• 429 Too Many Requests — 限流。请求频率超过阈值。响应头必须包含 Retry-After。

// 422 Unprocessable Entity 标准错误体
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/order-status-conflict",
  "title": "Order status transition not allowed",
  "status": 422,
  "detail": "Cannot cancel an order in 'shipped' status",
  "instance": "/api/v2/orders/ord-20250301-001/cancel",
  "errors": [
    {
      "field": "status",
      "code": "INVALID_TRANSITION",
      "message": "Current status 'shipped' does not allow 'cancelled'"
    }
  ]
}

2.5 5xx 服务端错误系列 — 安全合规红线

5xx 系列表示服务端无法完成合法请求。在安全合规视角下，5xx 响应是信息泄露的高危通道。

2.6 状态码选择流程与最佳实践

以下 SVG 流程图展示了后端 API 设计时选择正确状态码的决策路径，帮助开发者在契约设计阶段避免语义混淆。

2.7 状态码与错误码断言映射表

在 OpenAPI 契约测试中，每个状态码必须与特定的错误码枚举值形成固定映射。以下表格展示了后端安全合规场景下的标准映射关系：

2.8 状态码在 OpenAPI 契约中的声明规范

OpenAPI 3.0 要求每个响应必须显式声明状态码及其 schema。以下是一个符合安全合规要求的契约片段：

paths:
  /api/v2/orders/{orderId}/cancel:
    post:
      summary: 取消订单
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            pattern: '^ord-\d{14}-\d{3}$'
      responses:
        '200':
          description: 取消成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderCancelResponse'
        '401':
          description: 未认证
          headers:
            WWW-Authenticate:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 订单不存在
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: 订单状态不允许取消
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: 服务端内部错误
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'