3. OpenAPI 与缓存的关系：为什么需要在 OpenAPI 中定义缓存、缓存对 API 性能的影响

在微服务与 API 网关架构中，缓存是提升系统吞吐量、降低延迟的核心手段。然而，许多团队在定义 OpenAPI 契约时完全忽略了缓存语义，导致网关、客户端与服务器之间对缓存策略的理解不一致，最终引发数据不一致或性能瓶颈。本章将系统阐述 OpenAPI 与缓存之间的双向关系，并解释为什么缓存策略必须成为 API 契约的一部分。

3.1 为什么需要在 OpenAPI 中定义缓存

OpenAPI 规范不仅描述接口的输入输出，还应描述接口的运行时行为。缓存策略属于运行时行为的关键组成部分。在 OpenAPI 中显式定义缓存，能够带来以下核心价值：

3.2 缓存对 API 性能的影响

缓存对 API 性能的影响是双面的。合理的缓存策略可以显著提升性能，而不当的缓存则可能引入数据陈旧、缓存雪崩等问题。以下从三个关键指标分析缓存的影响：

• 延迟（Latency）： 缓存命中时，响应时间可从 50-200ms 降至 1-5ms，降低 90% 以上。
• 吞吐量（Throughput）： 缓存可吸收重复请求，使服务器在相同资源下处理更多请求，吞吐量提升 3-10 倍。
• 后端负载（Backend Load）： 缓存减少对数据库或下游服务的调用次数，降低 CPU、内存与连接池压力。

3.3 缓存策略在 OpenAPI 中的表达方式

OpenAPI 3.x 本身并未提供专用的 cache 字段，但可以通过以下标准扩展与响应头描述来定义缓存策略：

openapi: 3.0.3
info:
  title: 用户信息 API
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      summary: 获取用户详情
      parameters:
        - name: If-None-Match
          in: header
          schema:
            type: string
      responses:
        '200':
          description: 成功返回用户信息
          headers:
            Cache-Control:
              schema:
                type: string
                example: "public, max-age=600"
            ETag:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '304':
          description: 资源未修改（条件请求缓存命中）

3.4 缓存与 API 领域边界的关系

缓存策略的制定不能脱离 API 的领域边界。不同领域对缓存的要求截然不同：

• 读密集型领域（如商品详情、内容列表）： 适合长时间缓存（分钟级），使用 public 范围。
• 写密集型领域（如订单创建、库存扣减）： 通常不缓存或仅缓存 private 范围，TTL 极短。
• 用户个性化领域（如推荐、通知）： 必须使用 private 缓存，且需结合用户 ID 作为缓存键。
• 实时性要求高的领域（如交易状态、价格）： 使用条件请求（ETag/Last-Modified）而非固定 TTL。

3.5 缓存策略决策流程

以下 SVG 图展示了在 OpenAPI 契约中定义缓存策略的决策流程，帮助架构师根据领域特征选择正确的缓存模式：

3.6 在 OpenAPI 中定义缓存的最佳实践

1. 优先使用标准响应头： 在 OpenAPI 的 headers 中定义 Cache-Control、ETag、Last-Modified，确保与 HTTP 标准兼容。
2. 使用 x- 扩展字段补充元数据： 如 x-cache-ttl、x-cache-scope、x-cache-key，为网关和代码生成工具提供额外信息。
3. 区分领域边界： 每个领域边界内的缓存策略独立定义，避免跨领域缓存污染。
4. 为条件请求定义参数： 在 parameters 中声明 If-None-Match 和 If-Modified-Since，使客户端能够参与缓存协商。
5. 在文档中标注缓存行为： 在 description 字段中简要说明缓存策略，帮助开发者快速理解。