2. OpenAPI 契约基础回顾：核心元素与双重理念

在任务调度平台中，OpenAPI 契约不仅是接口描述文件，更是性能调优与资源优化的起点。本节回顾 OpenAPI 规范的核心元素，并深入阐释“契约即文档”与“契约即测试”两大理念，为后续的性能分析奠定基础。

2.1 OpenAPI 规范核心元素

一个标准的 OpenAPI 契约由路径、参数、请求体、响应等核心元素构成。下表总结了各元素在任务调度场景中的典型用途与性能关注点：

2.2 路径与参数：接口的骨架

路径定义了资源的访问入口，参数则控制请求的过滤与分页。在任务调度平台中，常见的路径设计模式包括：

• 集合路径：/api/v1/tasks —— 用于列出或创建任务
• 实例路径：/api/v1/tasks/{taskId} —— 用于获取、更新或删除单个任务
• 动作路径：/api/v1/tasks/{taskId}/execute —— 触发任务立即执行

参数按位置分为路径参数、查询参数、请求头参数。以下是一个典型的 OpenAPI 参数定义片段：

parameters:
  - name: taskId
    in: path
    required: true
    schema:
      type: string
      format: uuid
    description: 任务唯一标识
  - name: status
    in: query
    required: false
    schema:
      type: string
      enum: [pending, running, completed, failed]
    description: 按任务状态过滤

2.3 请求体与响应：数据的载体

请求体与响应是性能调优的核心战场。任务调度平台中，创建任务与查询任务列表是最频繁的操作，其数据模型直接影响序列化/反序列化性能。

以下是一个创建任务的请求体定义示例：

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required: [name, cron]
        properties:
          name:
            type: string
            maxLength: 128
            description: 任务名称
          cron:
            type: string
            pattern: '^(\S+\s+){4}\S+$'
            description: Cron 表达式
          timeout:
            type: integer
            minimum: 1
            maximum: 86400
            default: 3600
            description: 超时时间（秒）

响应设计应遵循“按需返回”原则，避免返回不必要的字段。对于列表接口，应包含分页元数据：

responses:
  '200':
    description: 任务列表
    content:
      application/json:
        schema:
          type: object
          properties:
            total:
              type: integer
              description: 总任务数
            page:
              type: integer
            size:
              type: integer
            items:
              type: array
              items:
                $ref: '#/components/schemas/TaskSummary'

2.4 契约即文档：从规范到可执行文档

“契约即文档”意味着 OpenAPI 规范本身就是一份精确、可读的接口文档。相比传统 Word 或 Wiki 文档，OpenAPI 契约具有以下优势：

• 机器可读：Swagger UI、Redoc 等工具可自动生成交互式文档
• 版本可控：契约文件可纳入 Git 管理，变更可追溯
• 单源真理：接口定义、校验规则、示例数据全部集中在同一份文件中

下图展示了契约即文档的工作流：

2.5 契约即测试：从规范到自动化验证

“契约即测试”将 OpenAPI 规范转化为可执行的测试用例，确保实现与契约始终保持一致。在任务调度平台中，契约测试覆盖以下维度：

• 请求校验：验证请求参数类型、格式、必填项是否符合契约
• 响应校验：验证响应状态码、响应体结构与字段类型
• 边界测试：测试参数最小值、最大值、空值、非法枚举值等场景
• 性能基线：在契约测试中嵌入响应时间断言，防止性能退化

下图展示了契约即测试在 CI/CD 流水线中的位置：

2.6 双重理念对性能调优的启示

“契约即文档”与“契约即测试”不仅是开发规范，更是性能调优的基础设施：