缓存治理

何时使用

• 要给接口加缓存;
• 缓存命中率低、数据库压力大;
• 线上出现缓存穿透、击穿、雪崩;
• 缓存和数据库数据不一致;
• 用户说"帮我看下缓存怎么设计的"。

使用步骤

第 1 步:明确缓存目标

先确认:

1. 缓存什么数据、给谁用;
2. 数据更新频率和一致性要求;
3. 读多写少吗,缓存收益在哪;
4. 命中率目标多少。

不是所有数据都该缓存,先判断收益再动手。

第 2 步:设计 key 与 TTL

key 设计:

• 带业务前缀和版本:user:info:v2:{id};
• 包含影响数据的维度(租户、语言、币种);
• 有明确的 key 规范,方便排查和清理。

TTL 设计:

• 每个 key 有 TTL,或者有明确的"为什么不过期";
• 集中过期的 key 做 TTL 随机化(偏移不超过基础值 10%);
• 热点 key 单独处理(互斥锁或逻辑过期);
• TTL 和业务一致性能接受的窗口匹配。

第 3 步:防御三类故障

第 4 步:处理一致性

• 更新数据时先删缓存再更新数据库(缓存侧),或先更新数据库再删缓存(推荐);
• 缓存和数据库的最终一致,靠 TTL 兜底;
• 不要在更新事务里直接改缓存,容易和数据库状态不一致;
• 一致性要求高的数据,考虑"数据库为唯一事实源"。

第 5 步:监控与收尾

上线前确认:

• 命中率、回源率、缓存延迟有监控;
• key 过期和清理有告警;
• 缓存服务不可用时,业务有降级路径(直接查库,不能雪崩式报错)。

输出:

# 缓存设计说明

## 缓存内容与目标
## key 与 TTL 规范
## 一致性策略
## 故障防御
## 监控指标

输入与输出

• 输入:缓存需求或现有缓存代码;
• 输出:缓存设计说明 + 代码改动。

示例

需求: 商品详情接口加缓存,数据变更不频繁。

设计:

• key:product:detail:v1:{id};
• TTL:10 分钟 + 随机 ±10% 防雪崩;
• 更新:修改商品后删除对应 key,下次读取重建;
• 穿透:查不到的商品缓存空值 1 分钟;
• 监控:命中率、回源 QPS。

参考

三类故障的防御方案、key/TTL 规范和一致性策略见 references/FAILURE_MODES.md。

辅助脚本

scripts/cache_key_scanner.py 扫描代码中的缓存 key 写法,标记无前缀、缺版本、set 无 TTL 等问题:

python scripts/cache_key_scanner.py <目录或文件>

脚本只做标记,结论需要人确认。

注意事项

• 缓存不是万能的:写多读少、一致性要求极高的数据别缓存;
• key 规范要能一眼看懂,不然排查靠猜;
• TTL 随机化偏移别太大,会拉长一致性窗口;
• 加缓存后必须验证:命中率上来、数据库压力下降、数据一致;
• 缓存服务挂了要有降级,不能因为缓存把接口搞挂。

不适用场景

• 数据一致性要求严格,业务无法接受缓存窗口(先和业务确认);
• 缓存服务选型问题(Redis 连接/部署,那是另一件事);
• 用户只是问 Redis 基础用法。

验证方式

1. 触发:"加个缓存""缓存穿透了""缓存不一致";
2. 检查:key/TTL 规范明确,三类故障有防御,一致性有方案;
3. 走查:压测或观察命中率和回源率,确认达标。