📚 课程目录第4章 OpenAPI契约基础

4. OpenAPI 契约基础：OpenAPI 3.0 规范简介、API 端点定义、请求/响应模型

在构建 RabbitMQ 消息重试系统时，API 契约是连接消息生产者、消费者与重试管理平台的核心纽带。OpenAPI 3.0 规范（原 Swagger）提供了一种语言无关的接口描述方式，使得团队能够精确地定义“消息重试”相关的 RESTful 端点、请求结构、响应格式以及错误处理策略。本节将系统性地介绍 OpenAPI 3.0 的核心概念，并围绕消息重试场景，定义关键的 API 端点与数据模型。

4.1 OpenAPI 3.0 规范核心要素

OpenAPI 3.0 规范以 JSON 或 YAML 格式描述 API 的完整生命周期。对于消息重试系统，以下三个核心对象是定义契约的基础：

核心对象	作用	消息重试场景示例
Paths	定义 API 端点及其支持的 HTTP 方法	`/api/retries`、`/api/retries/{id}/ack`
Components / Schemas	定义请求体与响应体的数据结构	`RetryMessage`、`RetryStatus`、`ErrorResponse`
Parameters	定义路径参数、查询参数、请求头	`retryId`、`status`、`X-Request-Id`

实践建议：在定义消息重试 API 时，优先使用 components/schemas 复用数据模型，避免在多个端点中重复定义相同的结构。这有助于保持契约的一致性和可维护性。

4.2 消息重试 API 端点定义

基于 RabbitMQ 消息重试的典型生命周期，我们定义以下核心端点。每个端点都对应一个明确的业务操作：

查询待重试消息列表：GET /api/retries — 支持分页、状态过滤、时间范围筛选。
获取单条重试消息详情：GET /api/retries/{retryId} — 返回消息体、重试次数、错误堆栈。
手动触发重试：POST /api/retries/{retryId}/retry — 立即将消息重新投递到目标队列。
确认消费（ACK）：POST /api/retries/{retryId}/ack — 标记消息已成功处理，从重试表中移除。
死信处理：POST /api/retries/{retryId}/dead-letter — 将消息转入死信队列，停止重试。

  端点设计原则：每个端点只负责一个业务动作，避免在同一个端点中混合“重试”与“确认”逻辑。清晰的端点职责有助于后续的故障排查和监控埋点。

4.3 请求与响应模型定义

以下 YAML 片段展示了 OpenAPI 3.0 中 RetryMessage 模型的定义，它包含了消息重试系统所需的核心字段：

components:
  schemas:
    RetryMessage:
      type: object
      required:
        - messageId
        - queueName
        - payload
        - retryCount
        - maxRetries
        - status
      properties:
        messageId:
          type: string
          format: uuid
          description: 消息唯一标识
        queueName:
          type: string
          description: 目标队列名称
        payload:
          type: string
          description: 消息体（JSON 序列化字符串）
        retryCount:
          type: integer
          minimum: 0
          description: 当前已重试次数
        maxRetries:
          type: integer
          minimum: 1
          description: 最大允许重试次数
        status:
          type: string
          enum: [pending, retrying, acked, dead_lettered]
          description: 消息当前状态
        lastError:
          type: string
          description: 最近一次消费失败的错误信息
        createdAt:
          type: string
          format: date-time
          description: 消息首次进入重试系统的时间

对应的响应模型 RetryListResponse 用于分页查询场景：

    RetryListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RetryMessage'
        totalCount:
          type: integer
          description: 符合条件的消息总数
        page:
          type: integer
          description: 当前页码
        pageSize:
          type: integer
          description: 每页条数

4.4 OpenAPI 契约与消息重试流程的映射

下面的 SVG 图展示了 OpenAPI 端点如何映射到 RabbitMQ 消息重试的完整流程，从消息消费失败到最终的死信处理：

4.5 错误响应模型与故障排查

在消息重试系统中，错误响应必须包含足够的信息以支持快速定位问题。以下 ErrorResponse 模型定义了统一的错误结构：

    ErrorResponse:
      type: object
      required:
        - code
        - message
        - timestamp
      properties:
        code:
          type: string
          description: 业务错误码（如 RETRY_QUEUE_FULL、MESSAGE_NOT_FOUND）
        message:
          type: string
          description: 人类可读的错误描述
        timestamp:
          type: string
          format: date-time
          description: 错误发生时间
        details:
          type: object
          description: 可选的错误详情（如失败原因、建议操作）
          properties:
            retryId:
              type: string
            queueName:
              type: string
            reason:
              type: string

常见陷阱：不要在错误响应中暴露 RabbitMQ 内部连接字符串、密码或完整的堆栈跟踪。使用业务错误码（如 RETRY_QUEUE_FULL）替代原始异常信息，既保证安全性，又便于客户端程序化处理。

4.6 契约版本管理与兼容性

OpenAPI 契约本身也需要版本管理。对于消息重试系统，建议遵循以下版本策略：

主版本号：当端点路径、请求/响应结构发生不兼容变更时递增（如 /v1/retries → /v2/retries）。
次版本号：当新增可选字段或端点时递增，不破坏现有消费者。
补丁版本号：当修正描述、示例值或文档错误时递增。

在 OpenAPI 3.0 中，可以通过 info.version 字段声明契约版本，并在 servers 字段中指定基础路径：

openapi: 3.0.3
info:
  title: RabbitMQ 消息重试管理 API
  version: 1.2.0
servers:
  - url: https://api.example.com/v1
    description: 生产环境