4. OpenAPI 迁移前后缓存架构对比
在 OpenAPI 迁移项目中，缓存架构的变更往往是影响系统性能和稳定性的关键因素。旧架构的缓存策略通常围绕单体应用或内部 RPC 调用设计，而新架构则需适配 API 网关、微服务及外部流量特征。本节将从缓存策略、架构设计及迁移带来的变化点三个维度进行对比分析。
4.1 旧架构缓存策略
旧架构通常采用“应用内缓存 + 分布式缓存”的两层模式，缓存键设计依赖内部服务名和方法签名，缺乏统一的 API 层抽象。
| 缓存层级 | 实现方式 | 缓存键示例 | 失效策略 |
|---|---|---|---|
| L1 本地缓存 | Caffeine / Guava Cache | userService::getUserById::123 |
TTL 5 分钟，最大容量 10,000 |
| L2 分布式缓存 | Redis Cluster | svc:user:getUserById:123 |
TTL 30 分钟，LRU 淘汰 |
| HTTP 响应缓存 | Nginx proxy_cache | URL 路径 + 查询参数 | 根据 Cache-Control 头 |
旧架构缓存痛点：
- 缓存键与内部服务强耦合，无法直接映射到 OpenAPI 路径。
- 缺乏统一的缓存注解或声明式配置，开发人员需手动管理缓存逻辑。
- 本地缓存与分布式缓存之间无一致性协调，容易出现脏读。
4.2 新架构缓存设计
迁移至 OpenAPI 后，缓存架构以 API 端点为中心，引入网关缓存、API 级缓存注解和缓存键标准化机制。
新架构缓存设计要点：
- 网关缓存：在 API 网关层（如 Kong、APISIX）配置基于 OpenAPI 路径的缓存规则，减少后端压力。
- 缓存键标准化：统一使用
/api/v2/{resource}/{id}格式，避免键冲突。 - 声明式缓存注解：在微服务中引入
@Cacheable、@CacheEvict注解，降低缓存管理复杂度。 - 缓存预热：针对高频 API 端点，在服务启动时执行缓存预热脚本。
4.3 迁移带来的变化点
从旧架构迁移到新缓存架构，以下变化点需要在集成测试中重点覆盖：
| 变化维度 | 旧架构 | 新架构 | 测试关注点 |
|---|---|---|---|
| 缓存键格式 | svc:method:param |
/api/v2/{resource}/{id} |
键冲突、键长度、特殊字符转义 |
| 缓存粒度 | 方法级（粗粒度） | API 端点级（细粒度） | 部分更新时缓存失效范围 |
| 缓存位置 | 应用本地 + Redis | 网关 + Redis + 本地（可选） | 网关缓存与后端缓存一致性 |
| 失效策略 | TTL + 手动清除 | TTL + 事件驱动失效 | 事件丢失或延迟导致脏数据 |
| 缓存穿透防护 | 无统一防护 | 布隆过滤器 + 空值缓存 | 布隆过滤器误判率、空值缓存 TTL |
迁移风险提示：
- 缓存键格式变更可能导致旧缓存数据无法命中，需在迁移窗口期执行缓存清理或双写过渡。
- 网关缓存引入后，需验证 Cache-Control 头是否正确传递，避免浏览器或 CDN 缓存与网关缓存冲突。
- 事件驱动失效依赖消息队列，需测试队列积压或消费失败场景下的缓存一致性。
4.4 缓存架构对比总结
下表从六个关键维度对迁移前后的缓存架构进行总结性对比：
| 维度 | 旧架构 | 新架构 | 迁移影响 |
|---|---|---|---|
| 缓存键设计 | 内部服务名 + 方法签名 | OpenAPI 路径 + 参数 | 需全量刷新缓存 |
| 缓存层级 | 应用本地 + 分布式 | 网关 + 分布式 + 可选本地 | 增加网关层测试 |
| 失效机制 | TTL + 手动 | TTL + 事件驱动 | 需验证事件可靠性 |
| 穿透防护 | 无 | 布隆过滤器 + 空值缓存 | 需测试误判和空值场景 |
| 一致性要求 | 最终一致性 | 强一致性（关键路径） | 需引入分布式锁或版本号 |
| 监控与可观测性 | 基础命中率监控 | 全链路缓存追踪 + 慢查询告警 | 需集成 OpenTelemetry |