4. 接口契约定义：OpenAPI/Swagger规范、契约文件结构、版本管理策略

在认证授权平台的 CI/CD 流水线中，接口契约是自动校验的核心依据。契约定义的质量直接决定了校验的准确性与可维护性。本节将深入讲解基于 OpenAPI/Swagger 规范的契约定义方法、标准文件结构以及面向流水线的版本管理策略。

4.1 OpenAPI/Swagger 规范选型

OpenAPI 规范（原 Swagger 规范）是目前业界最广泛使用的 RESTful API 描述标准。在认证授权平台中，我们推荐使用 OpenAPI 3.0.3 或 3.1.0 版本，相较于 Swagger 2.0，其在以下方面更适合契约自动校验：

4.2 契约文件标准结构

一个面向 CI/CD 自动校验的契约文件，需要遵循清晰的分层结构。以下是一个认证授权平台 auth-api.yaml 的标准骨架：

openapi: "3.0.3"
info:
  title: 认证授权平台接口契约
  version: "2.1.0"
  description: 统一认证、OAuth2 授权、令牌管理、用户会话接口定义

servers:
  - url: https://api.auth.example.com/v2
    description: 生产环境
  - url: https://staging-api.auth.example.com/v2
    description: 预发布环境

paths:
  /oauth/token:
    post:
      summary: 获取访问令牌
      operationId: getAccessToken
      tags: [OAuth2]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: 成功返回令牌
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /oauth/introspect:
    post:
      summary: 令牌内省
      operationId: introspectToken
      tags: [OAuth2]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                token:
                  type: string
                token_type_hint:
                  type: string
                  enum: [access_token, refresh_token]
      responses:
        '200':
          description: 内省结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntrospectionResponse'

components:
  schemas:
    TokenRequest:
      type: object
      required: [grant_type, client_id, client_secret]
      properties:
        grant_type:
          type: string
          enum: [authorization_code, client_credentials, refresh_token, password]
        client_id:
          type: string
        client_secret:
          type: string
        code:
          type: string
        redirect_uri:
          type: string
          format: uri
        refresh_token:
          type: string

    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
        refresh_token:
          type: string
        scope:
          type: string

    IntrospectionResponse:
      type: object
      properties:
        active:
          type: boolean
        sub:
          type: string
        scope:
          type: string
        client_id:
          type: string
        exp:
          type: integer
        iat:
          type: integer

  responses:
    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              error_description:
                type: string
    Unauthorized:
      description: 认证失败
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  securitySchemes:
    OAuth2Client:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.auth.example.com/v2/oauth/token
          scopes:
            read: 读取用户信息
            write: 写入用户数据

4.3 契约版本管理策略

在 CI/CD 流水线中，契约版本管理需要解决三个核心问题：向前兼容性判断、多版本共存、版本与代码的绑定关系。以下是推荐的策略：

4.3.1 语义化版本 + 兼容性标记

采用 MAJOR.MINOR.PATCH 格式，并在契约元数据中增加兼容性声明：

info:
  version: "2.1.0"
  x-compatibility:
    backward-compatible: true
    breaking-changes: false
    deprecated-endpoints: ["/v1/oauth/token"]

• MAJOR：不兼容的 API 变更（删除端点、修改必填字段、更改响应结构）。
• MINOR：向后兼容的新增（增加可选字段、新增端点、新增响应码）。
• PATCH：描述性修正（修正示例值、更新描述、修复 schema 格式错误）。

4.3.2 契约与代码的绑定策略

4.3.3 版本演进生命周期

在流水线中，每个契约版本应经历以下阶段：

1. 草案（Draft）：新端点或变更在 feature 分支上定义，仅用于内部评审。
2. 预览（Preview）：合并到 main 分支，标记为 2.1.0-preview.1，允许测试团队提前集成。
3. 稳定（Stable）：通过兼容性校验和自动化测试后，发布正式版本 2.1.0。
4. 废弃（Deprecated）：旧版本端点标记 deprecated: true，在响应头中添加 Sunset 字段。
5. 下线（Sunset）：达到下线日期后，从契约文件中移除，流水线中对应的校验规则自动失效。

4.4 契约文件结构总览（SVG）

下图展示了认证授权平台契约文件的完整结构层次，以及各组件在自动校验流水线中的角色：

4.5 契约文件拆分策略

当认证授权平台接口规模增长后，单个 YAML 文件会变得难以维护。推荐按以下维度进行拆分：

4.6 契约文件版本演进流程（SVG）

下图展示了契约从草案到下线的完整生命周期，以及每个阶段在流水线中的自动校验动作：

4.7 契约定义最佳实践清单

• 必填字段显式声明：在 schema 中使用 required 数组明确标记，避免流水线校验时产生歧义。
• 枚举值完整列举：对于 grant_type、token_type 等有限取值字段，使用 enum 穷举所有合法值。
• 错误响应标准化：所有 4xx/5xx 响应使用统一的 ErrorResponse schema，包含 error、error_description、error_uri 字段。
• 示例值覆盖边界：每个 schema 至少提供正常示例和错误示例，流水线可据此生成正向和异常测试用例。
• 扩展字段预留：使用 x- 扩展字段携带流水线元数据（如 x-test-timeout、x-rate-limit），不污染标准字段。
• 禁止硬编码环境地址：servers.url 使用 {baseUrl} 占位符，流水线通过环境变量注入实际地址。