📚 课程目录第3章 OpenAPI契约基础

3. OpenAPI 契约基础：核心元素回顾

在缓存一致性治理中，错误处理链路的设计必须依赖一份精确、可执行的接口契约。OpenAPI 规范（原 Swagger 规范）正是定义这份契约的行业标准。本章将回顾 OpenAPI 规范的四个核心元素：路径、参数、响应码与 Schema，为后续构建缓存失效与错误传播的契约化治理打下基础。

3.1 路径（Path）：接口的入口标识

路径是 API 的端点地址，也是契约的骨架。在 OpenAPI 中，每个路径对应一个相对 URL，并关联一个或多个 HTTP 方法（GET、POST、PUT、DELETE 等）。路径支持静态段与动态参数占位符。

  关键规则：路径必须以 / 开头，且不能包含查询字符串。查询参数必须在 parameters 字段中定义。

paths:
  /cache/entries/{entryId}:
    get:
      summary: 获取缓存条目
      parameters:
        - name: entryId
          in: path
          required: true
          schema:
            type: string
    delete:
      summary: 删除缓存条目
      parameters:
        - name: entryId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 删除成功，无返回体
        '404':
          description: 缓存条目不存在

3.2 参数（Parameter）：请求的输入控制

参数定义了客户端如何向服务端传递数据。OpenAPI 支持四种参数位置：path、query、header、cookie。每个参数必须声明名称、位置、是否必填以及数据类型。

参数位置	说明	缓存治理典型场景
`path`	嵌入在 URL 路径中，如 `/cache/{key}`	指定缓存键
`query`	URL 问号后的键值对，如 `?ttl=60`	设置缓存过期时间
`header`	HTTP 头部字段	传递缓存版本号或追踪 ID
`cookie`	HTTP Cookie	会话级缓存标识

最佳实践：在缓存失效接口中，将缓存键放在 path 参数中，将失效策略（如级联深度）放在 query 参数中，保持路径的幂等性。

3.3 响应码（Response Code）：错误链路的信号灯

响应码是服务端向客户端传达处理结果的核心信号。在缓存一致性治理中，错误处理链路依赖精确的响应码来触发重试、降级或告警。OpenAPI 要求每个操作至少定义一个成功响应，并强烈建议定义所有可能的错误响应。

responses:
  '200':
    description: 缓存命中，返回数据
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/CacheEntry'
  '404':
    description: 缓存未命中
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
  '503':
    description: 缓存服务不可用（如 Redis 宕机）
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'

常见陷阱：很多团队只定义 200 响应码，忽略 4xx/5xx 错误响应。这会导致客户端无法区分“缓存未命中”与“缓存服务异常”，从而引发错误的降级策略。

3.4 Schema：数据结构的类型契约

Schema 是 OpenAPI 中最核心的复用单元，它使用 JSON Schema 子集定义请求体与响应体的数据结构。在缓存治理中，Schema 确保缓存数据、错误对象、分页信息等具有一致的类型约束。

components:
  schemas:
    CacheEntry:
      type: object
      required:
        - key
        - value
        - ttl
      properties:
        key:
          type: string
          description: 缓存键
        value:
          type: string
          description: 缓存值（JSON 序列化字符串）
        ttl:
          type: integer
          description: 剩余生存时间（秒）
        created_at:
          type: string
          format: date-time
          description: 创建时间
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: 错误码，如 CACHE_MISS、CACHE_UNAVAILABLE
        message:
          type: string
          description: 人类可读的错误描述
        trace_id:
          type: string
          description: 链路追踪 ID，用于排查

3.5 核心元素关系图

下图展示了 OpenAPI 契约中路径、参数、响应码与 Schema 之间的协作关系，以及它们在缓存一致性治理中的角色定位。

3.6 元素组合：一个完整的缓存失效接口示例

将上述四个元素组合起来，可以定义出一个完整的缓存失效接口。以下示例展示了如何通过契约精确描述“按前缀批量失效缓存”的操作。

paths:
  /cache/invalidate:
    post:
      summary: 按前缀批量失效缓存
      parameters:
        - name: X-Cache-Version
          in: header
          required: true
          schema:
            type: string
          description: 缓存版本号，用于防止并发覆盖
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prefix
              properties:
                prefix:
                  type: string
                  description: 缓存键前缀，如 "user:123:*"
                recursive:
                  type: boolean
                  default: false
                  description: 是否递归失效子前缀
      responses:
        '202':
          description: 失效请求已接受，异步执行
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidationReceipt'
        '400':
          description: 请求参数错误（如 prefix 为空）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 缓存服务暂时不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

设计要点：该接口使用 202 Accepted 而非 200 OK，表明失效操作是异步的。客户端收到 202 后，应通过轮询或回调获取最终结果。这种设计在缓存一致性治理中非常常见，用于解耦失效操作与业务请求。

3.7 小结

路径、参数、响应码与 Schema 是 OpenAPI 契约的四大基石。在缓存一致性治理中：

路径定义了缓存操作的入口，需遵循 RESTful 风格与幂等性设计。
参数承载了缓存键、版本号、策略等关键信息，需明确必填与可选边界。
响应码是错误处理链路的信号灯，必须覆盖成功、业务错误与系统异常三类场景。
Schema确保了缓存数据与错误对象的结构一致性，是契约可执行性的保障。