4. 响应缓存策略设计：基于资源类型的缓存TTL设计原则与最佳实践
在OpenAPI契约中，缓存策略的核心是为不同资源类型分配差异化的生存时间（TTL）。错误的TTL设置会导致数据不一致或缓存命中率低下。本章从资源语义出发，建立一套可审计的TTL设计基线。
4.1 资源类型与缓存语义映射
根据资源变更频率和业务容忍度，可将API资源分为四类，每类对应不同的缓存行为基线：
| 资源类型 | 典型示例 | 变更频率 | 推荐TTL范围 | 缓存键策略 |
|---|---|---|---|---|
| 静态引用数据 | 国家代码、货币列表、配置字典 | 月度/季度 | 3600s – 86400s | 全路径 + 版本号 |
| 用户无关聚合数据 | 首页推荐、全局排行榜、天气概况 | 分钟级 | 60s – 600s | URL + 参数归一化 |
| 用户私有数据 | 个人资料、订单列表、消息通知 | 实时/秒级 | 0s – 30s（或私有缓存） | 用户ID + 资源ID |
| 写后即读一致性数据 | 支付状态、库存扣减、令牌验证 | 事务级 | 0s（禁止公共缓存） | 不缓存或私有缓存 |
审计要点：在OpenAPI契约的
response 对象中，必须显式声明 Cache-Control 头字段。对于写后即读类资源，应强制设置 no-store 而非 no-cache，以阻止网关或浏览器层任何形式的隐式缓存。
4.2 TTL设计原则：三层衰减模型
单一固定TTL无法应对网络抖动和负载变化。推荐采用三层衰减模型，在契约中通过 Cache-Control 扩展指令表达：
- 基准TTL（Base TTL）：资源在正常负载下的标准过期时间，定义在
max-age中。 - 衰减TTL（Stale TTL）：当源站返回5xx或超时时，允许缓存提供陈旧响应的最大时间，通过
stale-while-revalidate控制。 - 硬边界TTL（Hard TTL）：缓存绝对不允许超过此时间提供服务，通过
stale-if-error兜底。
契约示例（OpenAPI 3.0 响应头定义）：
responses:
'200':
description: 成功返回用户无关聚合数据
headers:
Cache-Control:
schema:
type: string
example: "public, max-age=300, stale-while-revalidate=60, stale-if-error=1200"
content:
application/json:
schema:
$ref: '#/components/schemas/AggregateData'4.3 基于资源类型的TTL设计流程
以下SVG图展示了从资源分类到TTL参数落地的完整决策流程：
4.4 常见反模式与审计红线
- 反模式1：全局统一TTL —— 所有资源使用相同的
max-age，导致静态资源过期过早、动态资源过期过晚。审计应检查契约中是否按路径或标签区分了缓存指令。 - 反模式2：忽略Vary头 —— 对
Accept-Encoding、Accept-Language等协商头未声明Vary，造成缓存投毒或错误响应。审计基线要求：任何公共缓存响应必须显式声明Vary。 - 反模式3：私有数据使用public指令 —— 用户私有数据若设置
public，中间缓存可能将用户A的数据返回给用户B。审计规则：包含用户标识的资源必须使用private或no-store。 - 反模式4：写接口返回可缓存响应 —— POST/PUT/DELETE 响应默认不应被缓存，除非明确设计为幂等查询。审计应标记所有非GET/HEAD方法中出现的
max-age指令。
安全审计红线：对于涉及认证令牌、支付回调、密码重置等敏感操作的端点，即使响应状态码为200，也必须设置
Cache-Control: no-store, private。任何允许公共缓存的此类端点应直接判定为高危缺陷。
4.5 最佳实践清单
| 实践项 | 操作说明 | 契约验证方式 |
|---|---|---|
| 1. 按资源粒度声明缓存 | 每个路径/操作独立定义 Cache-Control |
检查每个 response 对象是否包含缓存头 |
| 2. 使用标准化指令 | 优先使用 max-age、s-maxage、stale-while-revalidate |
禁止使用非标准扩展指令（如 X-Cache-TTL） |
| 3. 区分公共与私有缓存 | 用户相关数据用 private，聚合数据用 public |
审计工具扫描 private 资源是否误用 public |
| 4. 设置合理的衰减窗口 | stale-while-revalidate 不超过基准TTL的20% |
计算比例并标记异常值 |
| 5. 写操作显式禁止缓存 | POST/PUT/DELETE 响应设置 no-store |
正则匹配非GET方法响应头 |
通过以上设计原则与审计基线，团队可以在OpenAPI契约阶段提前发现缓存策略缺陷，避免将不一致的TTL策略带入生产环境。下一层级的审计将聚焦于缓存键的规范化与参数污染防护。