3. OpenAPI 契约基础：RESTful API 设计原则、OpenAPI 规范（Swagger）介绍、契约文件结构（info, paths, components）、版本管理

在任务调度平台的压力测试与性能调优工作中，OpenAPI 契约是连接开发、测试与运维的“单一事实来源”。本章将系统讲解 RESTful API 设计原则、OpenAPI 规范的核心概念、契约文件的三层结构以及版本管理策略，为后续的契约驱动压测奠定基础。

3.1 RESTful API 设计原则

REST（Representational State Transfer）是一种架构风格，而非协议。任务调度平台的 API 设计应遵循以下核心原则：

3.2 OpenAPI 规范（Swagger）介绍

OpenAPI 规范（原 Swagger 规范）是一种用于描述 RESTful API 的接口描述语言。它使用 JSON 或 YAML 格式定义 API 的端点、请求参数、响应结构、认证方式等。当前主流版本为 OpenAPI 3.0.x（3.0.3 为稳定版）和 3.1.x（兼容 JSON Schema 2020-12）。

以下是一个任务调度平台 OpenAPI 3.0 契约文件的精简示例：

openapi: "3.0.3"
info:
  title: 任务调度平台 API
  version: "2.1.0"
  description: 用于任务创建、查询、触发与监控的 RESTful 接口
servers:
  - url: https://api.scheduler.example.com/v2
paths:
  /jobs:
    get:
      summary: 查询任务列表
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, running, completed, failed]
      responses:
        '200':
          description: 成功返回任务列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
    post:
      summary: 创建新任务
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '201':
          description: 任务创建成功
          headers:
            Location:
              schema:
                type: string
                format: uri
components:
  schemas:
    Job:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum: [pending, running, completed, failed]
        createdAt:
          type: string
          format: date-time
    CreateJobRequest:
      type: object
      required:
        - name
        - cronExpression
      properties:
        name:
          type: string
        cronExpression:
          type: string
          example: "0 0/5 * * * ?"

3.3 契约文件结构：info, paths, components

OpenAPI 契约文件由三个核心顶层字段构成，它们共同定义了 API 的全貌：

3.4 版本管理

任务调度平台 API 的版本管理直接影响压测脚本的维护成本和向后兼容性。推荐采用以下策略：

在任务调度平台中，建议采用 URL 路径版本 + 语义化版本 的组合策略：

• 主版本（Major）：URL 路径体现，如 /v1/、/v2/，表示不兼容的 API 变更。
• 次版本（Minor）：在 OpenAPI 契约的 info.version 中体现，如 2.1.0，表示向后兼容的新功能。
• 修订版本（Patch）：在契约文件的 info.version 中体现，如 2.1.3，表示内部 bug 修复，不影响接口行为。