3. OpenAPI 契约基础：规范、定义与数据模型

在消息队列任务开发中，OpenAPI 契约充当了生产者与消费者之间的“通信宪法”。本章将系统讲解 OpenAPI 规范的核心概念、YAML/JSON 定义语法、API 端点描述方法以及数据模型建模方式，为后续基于契约驱动的消息队列任务开发奠定基础。

3.1 OpenAPI 规范简介

OpenAPI 规范（原 Swagger 规范）是一种用于描述 HTTP API 的标准化接口描述语言。它通过一份机器可读的契约文件，完整定义 API 的端点、请求参数、响应结构、认证方式以及数据模型。

OpenAPI 规范的主要版本对比：

3.2 YAML / JSON 定义语法

OpenAPI 契约支持 YAML 和 JSON 两种序列化格式。YAML 因其可读性高、注释支持好，成为社区首选；JSON 则更适合程序化生成与传输。

以下是一个消息队列任务 API 的 YAML 定义示例：

openapi: "3.0.3"
info:
  title: "消息队列任务管理 API"
  version: "1.0.0"
  description: "用于消息队列任务的创建、查询与状态管理"

servers:
  - url: https://api.example.com/v1
    description: 生产环境

paths:
  /tasks:
    post:
      summary: 创建消息队列任务
      operationId: createTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreateRequest'
      responses:
        '201':
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    TaskCreateRequest:
      type: object
      required:
        - queueName
        - messageBody
      properties:
        queueName:
          type: string
          description: 目标队列名称
          example: "order.payment"
        messageBody:
          type: string
          description: 消息体内容（JSON 字符串）
          example: '{"orderId": "12345", "amount": 99.9}'
        priority:
          type: integer
          description: 消息优先级（1-10）
          minimum: 1
          maximum: 10
          default: 5
        delaySeconds:
          type: integer
          description: 延迟投递秒数
          minimum: 0
          maximum: 900
          default: 0

JSON 格式等价定义（片段）：

{
  "openapi": "3.0.3",
  "info": {
    "title": "消息队列任务管理 API",
    "version": "1.0.0"
  },
  "paths": {
    "/tasks": {
      "post": {
        "summary": "创建消息队列任务",
        "operationId": "createTask",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskCreateRequest"
              }
            }
          }
        }
      }
    }
  }
}

3.3 API 端点与路径描述

OpenAPI 使用 paths 对象定义所有 API 端点。每个路径可以包含一个或多个 HTTP 方法（GET、POST、PUT、DELETE、PATCH 等）。

路径描述的核心要素：

• 路径模板：支持路径参数，如 /tasks/{taskId}
• 操作对象：包含 summary、operationId、parameters、requestBody、responses
• 参数类型：path（路径参数）、query（查询参数）、header（请求头）、cookie（Cookie 参数）
• 响应码：至少定义 2xx 成功响应和 4xx/5xx 错误响应

消息队列任务 API 的端点设计示例：

3.4 数据模型描述与 Schema 定义

OpenAPI 使用 components/schemas 定义可复用的数据模型。每个 Schema 遵循 JSON Schema 规范，支持基本类型、对象嵌套、数组、枚举、组合类型等。

消息队列任务场景中常见的数据模型：

数据模型定义示例（YAML）：

components:
  schemas:
    TaskResponse:
      type: object
      required:
        - taskId
        - status
        - createdAt
      properties:
        taskId:
          type: string
          format: uuid
          description: 任务唯一标识
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        status:
          $ref: '#/components/schemas/TaskStatus'
        createdAt:
          type: string
          format: date-time
          description: 任务创建时间
          example: "2025-03-15T10:30:00Z"
        queueName:
          type: string
          description: 目标队列名称
          example: "order.payment"
        priority:
          type: integer
          description: 消息优先级
          example: 5

    TaskStatus:
      type: string
      enum:
        - PENDING
        - PROCESSING
        - COMPLETED
        - FAILED
      description: "任务状态枚举：PENDING-待处理，PROCESSING-处理中，COMPLETED-已完成，FAILED-失败"

    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: 错误码
          example: "TASK_NOT_FOUND"
        message:
          type: string
          description: 错误描述
          example: "未找到指定的任务"
        requestId:
          type: string
          description: 请求追踪 ID
          example: "req-abc123"

3.5 契约驱动的消息队列任务开发流程

基于 OpenAPI 契约的消息队列任务开发遵循以下步骤：

1. 定义契约：使用 YAML/JSON 编写 OpenAPI 规范，明确所有 API 端点、请求/响应结构、数据模型
2. 生成代码：使用 OpenAPI Generator、Swagger Codegen 等工具生成服务端桩代码和客户端 SDK
3. 实现业务逻辑：在生成的接口基础上，填充消息队列的生产、消费、状态管理逻辑
4. 契约测试：使用 Dredd、Postman 等工具验证实现是否与契约一致
5. 文档发布：通过 Swagger UI、Redoc 等工具生成交互式 API 文档