3. OpenAPI 规范与缓存：核心字段与缓存策略

在微服务与 API 网关架构中，缓存是降低延迟、减少后端压力的关键手段。OpenAPI 3.0 规范通过标准字段定义了服务端与客户端之间的缓存契约。本章聚焦于 Cache-Control、ETag、Last-Modified 三个核心字段，并区分响应缓存与请求缓存的适用场景。

3.1 缓存相关字段详解

OpenAPI 规范在响应对象（Response Object）和头对象（Header Object）中定义了缓存字段。下表对比了三个字段的语义、使用位置与典型场景：

3.2 响应缓存 vs 请求缓存

缓存策略需要根据数据流向分为两类：

• 响应缓存（Response Cache）：缓存服务端返回的完整响应。适用于 GET 请求的幂等资源，如用户列表、配置信息。由网关或客户端根据 Cache-Control 指令决定存储时长。
• 请求缓存（Request Cache）：缓存客户端发出的请求结果，避免重复发送相同请求到后端。适用于查询参数固定的搜索、分页接口。通常由 API 网关或反向代理实现。

下表从多个维度对比两种缓存：

3.3 在 OpenAPI 规范中声明缓存字段

以下示例展示如何在 OpenAPI 3.0 的响应头中声明 Cache-Control、ETag 和 Last-Modified：

openapi: 3.0.0
info:
  title: 用户服务 API
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      summary: 获取用户详情
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回用户信息
          headers:
            Cache-Control:
              description: 缓存控制指令
              schema:
                type: string
                example: public, max-age=3600
            ETag:
              description: 资源实体标签
              schema:
                type: string
                example: "33a64df551425fcc55e4d42a148795d9f25f89d4"
            Last-Modified:
              description: 资源最后修改时间
              schema:
                type: string
                format: date-time
                example: Thu, 01 Dec 2025 16:00:00 GMT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

3.4 缓存一致性流程：条件请求

ETag 和 Last-Modified 通常与条件请求头配合使用，实现缓存一致性。下图展示了客户端与服务器之间的缓存验证流程：

3.5 缓存键设计与服务边界

在分布式系统中，缓存键的设计直接影响缓存命中率与一致性。OpenAPI 规范中的 parameters 定义决定了缓存键的组成：

• 基础缓存键：请求方法 + 路径 + 查询参数（按规范顺序排序）
• 扩展缓存键：加入 Accept、Authorization（需谨慎）等头字段
• 服务边界隔离：不同微服务的缓存键应包含服务标识，避免键冲突

3.6 缓存失效策略

缓存一致性不仅依赖写入时的 TTL，更需要主动失效机制。下表列出常见失效策略及其适用场景：