2. OpenAPI 3.0 基础回顾：规范核心概念、路径、参数、请求体、响应体定义

在深入缓存一致性治理的契约落地之前，必须重新夯实 OpenAPI 3.0 的核心基础。本章将聚焦于规范的核心概念、路径定义、参数声明、请求体与响应体的结构化描述，为后续错误处理与降级设计提供精确的契约锚点。

2.1 OpenAPI 3.0 核心概念与文档结构

OpenAPI 3.0 规范（原 Swagger 规范）是一种用于描述 HTTP API 的标准化接口描述语言。其核心目标是让机器和人能够理解 API 的能力，无需访问源代码或文档。一个标准的 OpenAPI 文档由以下几个顶层对象构成：

顶层字段 说明 缓存治理场景中的典型用途
openapi 规范版本号，必须为 3.0.x 确保工具链支持 3.0 特性（如 oneOf、discriminator）
info API 元信息（标题、版本、描述） 标注缓存策略版本，便于多版本共存治理
servers 基础 URL 列表，支持变量替换 区分缓存集群节点地址，实现动态路由
paths API 路径及操作（GET/POST/PUT/DELETE） 定义缓存键前缀与路径参数的映射关系
components 可复用的 schema、参数、响应、请求体 统一缓存失效响应、降级错误码的模型定义
tags 分组标签，用于文档分类 按缓存层级（L1/L2）或业务域分组
讲师提示： 在缓存一致性治理中，components 是复用度最高的部分。建议将 CacheInvalidationResponse、DegradationError 等通用模型全部抽取到 components/schemas 中，避免每个路径重复定义。

2.2 路径定义与操作对象

路径（Path）是 API 的入口点。在 OpenAPI 3.0 中，每个路径下可以包含一个或多个操作（Operation），每个操作对应一个 HTTP 方法。路径支持模板化参数，例如 /users/{userId}。

paths:
  /cache/entries/{key}:
    get:
      operationId: getCacheEntry
      summary: 获取缓存条目
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 缓存命中，返回数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CacheEntry'
        '404':
          description: 缓存未命中
          $ref: '#/components/responses/CacheMiss'
    delete:
      operationId: invalidateCacheEntry
      summary: 失效指定缓存条目
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 缓存失效成功
        '503':
          description: 缓存服务降级中
          $ref: '#/components/responses/DegradationResponse'
关键设计原则： 路径参数应直接映射为缓存键的组成部分。例如 /cache/entries/{key} 中的 {key} 就是 Redis 或本地缓存的精确键值。避免在路径中拼接额外前缀，保持契约与存储结构一一对应。

2.3 参数定义：路径、查询、头、Cookie

OpenAPI 3.0 支持四种参数位置（in 字段）：path、query、header、cookie。每个参数必须声明 name、in、schema，以及可选的 required、description、example。

参数位置 缓存治理典型场景 示例
path 缓存键主标识 /cache/{userId}/{resourceType}
query 缓存过滤条件、分页、TTL 覆盖 ?ttl=300&tags=profile,avatar
header 缓存版本号、降级标志、追踪 ID X-Cache-Version: 2.1
cookie 会话级缓存偏好 cache_preference=low_latency 
parameters:
  - name: X-Cache-Degradation
    in: header
    description: 客户端主动请求降级模式（stale / bypass / force_refresh）
    required: false
    schema:
      type: string
      enum: [stale, bypass, force_refresh]
    example: stale
避坑提醒： 头参数（header）在 OpenAPI 3.0 中默认不区分大小写，但实际 HTTP 头可能因框架而异。建议在契约中统一使用小写加连字符格式（如 x-cache-ttl），并在实现层做大小写归一化处理。

2.4 请求体定义：content、media type、schema

请求体（RequestBody）用于描述 POST、PUT、PATCH 等操作中客户端发送的数据。OpenAPI 3.0 使用 content 字段映射媒体类型（Media Type）到具体的 Schema。支持 application/json、application/xml、multipart/form-data 等。

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - key
          - value
          - ttl
        properties:
          key:
            type: string
            description: 缓存键
            example: "user:12345:profile"
          value:
            type: object
            description: 缓存值（JSON 对象）
          ttl:
            type: integer
            description: 过期时间（秒）
            minimum: 1
            maximum: 86400
            example: 3600
          tags:
            type: array
            items:
              type: string
            description: 缓存标签，用于批量失效
讲师提示： 在缓存写入场景中，建议将 ttl 和 tags 设计为可选字段。当客户端不传递时，服务端使用默认 TTL 和空标签集。这可以避免因客户端遗漏参数导致缓存永久有效或无法批量失效。

2.5 响应体定义：状态码、内容、头

响应体（Response）是 API 返回给客户端的数据结构。每个响应必须关联一个 HTTP 状态码，并可以包含 description、content、headers。在缓存治理中，响应头常用于传递缓存状态元数据。

responses:
  '200':
    description: 缓存命中，返回数据
    headers:
      X-Cache-Status:
        schema:
          type: string
          enum: [HIT, MISS, STALE]
        description: 缓存命中状态
      X-Cache-TTL-Remaining:
        schema:
          type: integer
        description: 剩余过期时间（秒）
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/CacheEntry'
  '503':
    description: 缓存服务降级
    headers:
      X-Degradation-Reason:
        schema:
          type: string
        description: 降级原因（如：redis_timeout / circuit_open）
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/DegradationResponse'

2.6 核心概念关系图

下图展示了 OpenAPI 3.0 文档中核心对象之间的层级关系，以及它们如何映射到缓存一致性治理的契约设计：

OpenAPI 3.0 核心概念与缓存治理映射 OpenAPI 3.0 核心概念与缓存治理映射 OpenAPI Document info (版本/标题) servers (基础URL) paths (路径集合) components (复用模型) /cache/{key} (路径) GET / DELETE (操作) parameters (参数) requestBody (请求体) responses (响应) 缓存治理映射说明 • parameters → 缓存键组成部分（路径参数）、缓存过滤条件（查询参数）、降级标志（头参数） • requestBody → 缓存写入时的 value、ttl、tags 等结构化数据 • responses → 缓存命中/未命中/降级状态码、X-Cache-Status 头、降级原因描述 • components → 复用 CacheEntry、DegradationResponse、CacheMiss 等模型定义

2.7 组件复用与 $ref 引用

OpenAPI 3.0 的 components 对象是契约复用的核心机制。通过 $ref 引用，可以避免在多个路径中重复定义相同的 schema、参数、响应或请求体。在缓存治理中，这是保证错误处理与降级设计一致性的关键手段。

components:
  schemas:
    CacheEntry:
      type: object
      properties:
        key:
          type: string
        value:
          type: object
        ttl:
          type: integer
        created_at:
          type: string
          format: date-time
    DegradationResponse:
      type: object
      required:
        - status
        - message
        - degraded_at
      properties:
        status:
          type: string
          enum: [degraded, fallback, stale]
        message:
          type: string
        degraded_at:
          type: string
          format: date-time
        fallback_source:
          type: string
          enum: [local_cache, db, default_value]
  responses:
    CacheMiss:
      description: 缓存未命中
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: "miss"
              suggestion:
                type: string
                example: "请先调用写入接口"
    DegradationResponse:
      description: 缓存服务降级
      headers:
        X-Degradation-Reason:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DegradationResponse'
最佳实践： 在缓存一致性治理项目中，建议将 components/responses 中的降级响应统一命名为 DegradationResponse，并在所有可能降级的操作中通过 $ref 引用。这样当降级策略调整时（例如新增降级原因字段），只需修改一处定义，所有路径自动同步。

2.8 参数序列化与缓存键生成

OpenAPI 3.0 定义了参数的序列化方式（style 和 explode 字段），这直接影响缓存键的生成规则。例如，查询参数 ?filter[name]=john&filter[age]=30 使用 deepObject 风格，缓存键应包含完整的嵌套结构。

参数位置 style explode 示例 缓存键生成结果
query form true ?tags=a,b,c cache:tags:a,b,c
query form false ?tags=a,b,c cache:tags:a%2Cb%2Cc
query spaceDelimited true ?tags=a&tags=b cache:tags:a|b
path simple false /users/42 cache:user:42
避坑提醒： 缓存键生成必须与 OpenAPI 参数序列化规则严格一致。如果契约中声明 style: form, explode: true，但实现层使用 explode: false 的序列化方式生成缓存键，将导致缓存命中率下降甚至数据错乱。建议在缓存中间件中直接复用 OpenAPI 的序列化库（如 swagger-parser）来保证一致性。

2.9 本章小结

← 上一章 📖 返回目录 下一章 →