4. OpenAPI 中的缓存声明：响应缓存标记、operationId 与缓存键设计、x-cache 扩展字段

在 OpenAPI 契约中声明缓存策略，是连接 API 设计与缓存基础设施的关键桥梁。本章聚焦三种核心声明方式：标准响应缓存标记、基于 operationId 的缓存键设计，以及通过 x-cache 扩展字段实现精细化控制。掌握这些技术，你就能在 API 文档中直接定义缓存行为，让网关、CDN 和客户端自动遵循统一规则。

4.1 响应缓存标记：标准化的缓存指令

OpenAPI 3.x 规范通过 Cache-Control 响应头字段声明缓存行为。在 API 契约中，你需要在响应的 headers 部分定义该字段，并指定其 schema 和示例值。这是最基础的缓存声明方式，兼容所有 HTTP 缓存中间件。

paths:
  /api/products:
    get:
      summary: 获取产品列表
      responses:
        '200':
          description: 成功返回产品列表
          headers:
            Cache-Control:
              schema:
                type: string
                example: public, max-age=300
          content:
            application/json:
              schema:
                type: array
              items:
                $ref: '#/components/schemas/Product'

4.2 operationId 与缓存键设计

operationId 是 OpenAPI 中每个操作的唯一标识符。在缓存系统中，operationId 可以作为缓存键的核心组成部分，确保不同 API 操作的缓存不会互相污染。缓存键的设计直接影响缓存命中率和数据一致性。

缓存键通常由以下部分组合而成：

• operationId：唯一标识 API 操作，如 getProductById。
• 请求参数：路径参数、查询参数、请求头等。
• 用户身份标识（可选）：用于私有缓存场景。
• 版本号：API 版本或缓存版本控制。

# 缓存键设计示例
# operationId: getProductById
# 缓存键格式: {operationId}:{pathParam_id}:{queryParam_currency}

# 请求: GET /products/123?currency=USD
# 缓存键: getProductById:123:USD

# 请求: GET /products/456?currency=EUR
# 缓存键: getProductById:456:EUR

4.3 x-cache 扩展字段：精细化缓存控制

标准 Cache-Control 无法覆盖所有缓存场景，例如缓存预热、TTL 分层、缓存组归属等。OpenAPI 的扩展字段机制（以 x- 开头）允许你自定义缓存元数据，这些元数据可以被网关、CDN 或缓存中间件解析执行。

常见的 x-cache 扩展字段包括：

paths:
  /api/users/{userId}/profile:
    get:
      operationId: getUserProfile
      x-cache:
        ttl: 600
        group: user-profile
        priority: high
        warmup: true
        key-parts:
          - pathParam: userId
          - header: Accept-Language
      responses:
        '200':
          description: 用户资料
          headers:
            Cache-Control:
              schema:
                type: string
                example: private, max-age=600

4.4 缓存声明架构总览

下图展示了 OpenAPI 契约中缓存声明的完整架构，从标准响应头到扩展字段，再到缓存键的生成逻辑。

4.5 缓存键设计模式对比

不同的缓存键设计模式适用于不同的业务场景。下表对比了三种常见模式：

4.6 缓存声明最佳实践

1. 显式声明缓存策略：每个 GET 操作都应包含 Cache-Control 响应头定义。
2. operationId 命名规范：使用 动词+名词 格式，如 getUserOrders，确保全局唯一。
3. 缓存键最小化：只将影响响应内容的参数纳入缓存键，通过 x-cache-key-parts 显式声明。
4. 缓存组管理：使用 x-cache-group 将相关操作归组，便于批量失效。
5. 版本控制：在缓存键或 x-cache 扩展中包含 API 版本号，避免版本升级导致缓存混乱。

# 完整缓存声明示例
paths:
  /v2/orders/{orderId}:
    get:
      operationId: getOrderById
      x-cache:
        ttl: 300
        group: orders
        priority: high
        key-parts:
          - pathParam: orderId
          - header: Authorization
      responses:
        '200':
          description: 订单详情
          headers:
            Cache-Control:
              schema:
                type: string
                example: private, max-age=300
            ETag:
              schema:
                type: string
                example: "abc123"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

4.7 缓存键生成流程

下图展示了从 OpenAPI 契约到最终缓存键的完整生成流程，帮助理解各组件如何协同工作。

4.8 常见问题与避坑指南