OpenAPI场景缓存一致性：服务边界与架构演进方案 - 第2节

2.1 OpenAPI 规范简介

OpenAPI 规范（原 Swagger 规范）是业界标准的、语言无关的 HTTP API 描述格式。它允许人类和计算机在不访问源码、文档或网络流量检查的情况下，发现和理解服务的功能。在缓存一致性场景中，OpenAPI 是定义服务边界、缓存键规则和失效契约的“单一事实来源”。

2.1.1 核心结构

一个标准的 OpenAPI 文档由以下顶层对象组成：

2.1.2 缓存扩展字段

OpenAPI 3.x 允许通过 x- 前缀定义自定义扩展，用于标注缓存策略：

paths:
  /products/{productId}:
    get:
      summary: 获取商品详情
      x-cache-config:
        ttl: 300
        scope: "user"
        invalidate-on: ["PUT", "DELETE"]
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

2.2 RESTful API 设计原则

REST（Representational State Transfer）是一种架构风格，而非协议。在缓存一致性场景中，RESTful 设计直接影响缓存的可缓存性（Cacheability）和失效粒度。

2.2.1 六大约束与缓存的关系

2.2.2 HTTP 方法与缓存语义

RESTful API 通过 HTTP 方法表达操作意图，缓存系统据此决定行为：

• GET — 安全且幂等，响应可被缓存。应返回 Cache-Control 和 ETag。
• HEAD — 同 GET 但不返回 body，缓存元数据可复用。
• POST — 非幂等，默认不可缓存。但可返回 303 See Other 重定向到可缓存的 GET 资源。
• PUT / PATCH — 幂等但非安全，通常用于更新，应触发相关 GET 缓存的失效。
• DELETE — 删除资源，必须使该资源及其集合的缓存失效。

2.3 缓存的基本概念与分类

缓存是将数据副本存储在临时存储层，以加速后续请求的技术。在 OpenAPI 场景中，缓存位于客户端、网关、反向代理或应用内部。

2.3.1 按存储位置分类

2.3.2 按失效策略分类

• TTL（Time-To-Live） — 写入后固定时间过期，简单但可能返回过期数据。
• TTI（Time-To-Idle） — 最后一次访问后固定时间过期，适合热点数据。
• 主动失效 — 数据变更时立即删除或更新缓存，一致性高但增加写路径复杂度。
• 被动失效 — 通过版本号或 ETag 对比，发现不一致时回源。
• LRU / LFU — 内存不足时淘汰策略，与数据一致性无关。

2.3.3 按一致性模型分类

2.4 OpenAPI 与缓存的映射关系

将 OpenAPI 规范与缓存策略结合，需要建立从 API 描述到缓存行为的精确映射。以下是核心映射规则：

2.5 本章小结

• OpenAPI 规范为缓存策略提供了结构化的描述载体，x-cache-* 扩展字段是团队协作的关键契约。
• RESTful 设计中的 HTTP 方法语义直接决定了缓存的可缓存性和失效触发条件。
• 缓存按存储位置、失效策略、一致性模型三个维度分类，OpenAPI 场景最常用“分布式缓存 + 主动失效 + 最终一致性”组合。
• 从 OpenAPI 文档到缓存规则表的映射流程，是构建自动化缓存治理的基础设施。