4. OpenAPI 契约基础：OpenAPI 3.0 规范核心元素

在缓存一致性治理体系中，OpenAPI 契约是连接业务逻辑与中间件配置的“单一事实源”。本章聚焦 OpenAPI 3.0 规范的四个核心元素——Paths、Parameters、Responses、Schemas，并阐述“契约即文档”与“契约即测试”的双重治理理念。

4.1 核心元素全景

OpenAPI 3.0 规范以 paths 为入口，通过 parameters 定义请求变量，responses 描述返回结构，schemas 提供类型约束。四者共同构成可机器解析、可人工阅读的接口契约。

4.2 Paths：端点即缓存入口

paths 对象声明了每个 API 端点的 HTTP 方法、操作 ID 和请求/响应结构。在缓存治理中，路径模板直接映射为缓存键的前缀。

paths:
  /users/{userId}/profile:
    get:
      operationId: getUserProfile
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 用户资料
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'

4.3 Parameters：缓存键的变量来源

parameters 定义了请求中可携带的变量，包括路径参数、查询参数、请求头参数。这些变量是缓存键组合的核心输入。

• 路径参数：直接嵌入 URL，如 /orders/{orderId}，适合唯一标识资源。
• 查询参数：通过 ?key=value 传递，如 ?page=1&size=20，适合分页/过滤。
• 请求头参数：如 Accept-Language，影响缓存变体（Vary）。

4.4 Responses：可缓存性声明

responses 不仅描述返回结构，还通过 headers 字段携带缓存控制指令。OpenAPI 3.0 允许在响应中显式声明 Cache-Control、ETag、Expires 等头信息。

responses:
  '200':
    description: 成功返回
    headers:
      Cache-Control:
        schema:
          type: string
          example: public, max-age=3600
      ETag:
        schema:
          type: string
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ProductList'

4.5 Schemas：数据模型与序列化契约

schemas 使用 JSON Schema 子集定义请求体和响应体的结构。在缓存治理中，Schema 决定了序列化/反序列化的一致性，直接影响缓存数据的正确性。

4.6 契约即文档与契约即测试

OpenAPI 契约在缓存治理中承担双重角色：

• 契约即文档：契约是缓存策略的权威描述，开发者和中间件运维人员通过契约理解哪些端点可缓存、缓存键如何构造、缓存有效期多长。
• 契约即测试：契约可自动生成缓存一致性测试用例，验证实际缓存行为是否与契约声明一致。例如，检测响应头中的 Cache-Control 是否与契约匹配。

4.7 契约驱动缓存治理流程

基于 OpenAPI 契约的缓存治理遵循以下步骤：

1. 契约定义：在 OpenAPI 文件中声明所有端点的缓存相关属性（Cache-Control、ETag、缓存键模板）。
2. 契约校验：使用 Spectral 等工具检查契约完整性，确保每个 GET 端点都有缓存声明。
3. 代码生成：从契约生成服务端桩代码和客户端 SDK，缓存逻辑自动嵌入。
4. 测试生成：基于契约生成缓存一致性测试用例，验证实际响应头与契约一致。
5. 监控对齐：运行时监控缓存命中率与契约预期对比，发现偏差即告警。