📚 课程目录第4章缓存键的版本化设计

4. 缓存键的版本化设计：键命名规范、版本号嵌入键名、版本前缀与命名空间

在微服务与领域驱动设计的架构中，缓存键不仅仅是简单的字符串，它承载着数据契约的语义。当领域模型发生演进时，若缓存键未携带版本信息，旧版数据将被错误地当作新版数据使用，导致数据污染与逻辑错乱。版本化设计的核心目标是在键层面建立不可变契约，确保不同版本的数据在缓存中隔离共存。

4.1 键命名规范：三段式结构

推荐采用三段式命名规范，将命名空间、领域实体与版本号显式编码到键名中，形成可解析、可路由的缓存键。

段位	名称	示例	说明
第一段	命名空间前缀	`order`	标识业务域或微服务，避免跨域键冲突
第二段	领域实体/聚合	`order:detail`	描述缓存数据的领域对象类型
第三段	版本号 + 唯一标识	`v2:12345`	版本号在前，实体ID在后，支持按版本前缀扫描

完整键示例：

order:order:detail:v2:12345
payment:payment:receipt:v1:98765
inventory:stock:item:v3:SKU-001

设计原则：版本号应紧跟在领域实体之后、唯一标识之前。这样既可以利用 Redis 的 KEYS 或 SCAN 命令按版本前缀批量操作，又不会破坏键的可读性。

4.2 版本号嵌入键名的三种策略

根据版本管理的粒度与运维复杂度，有三种主流的嵌入策略：

全局版本号：所有缓存键共享一个版本号（如 v3），升级时全量迁移。适合单体应用或版本耦合紧密的系统。
领域版本号：每个领域聚合根独立维护版本号（如 order:v2、payment:v1），支持按领域独立演进。适合微服务架构。
属性级版本号：在键名中嵌入字段级别的版本标识（如 user:profile:v2:email），用于细粒度缓存更新。适合高频变更的字段。

策略	粒度	升级成本	适用场景
全局版本号	粗	高（全量迁移）	单体应用、版本耦合紧密
领域版本号	中	中（按域迁移）	微服务、领域驱动设计
属性级版本号	细	低（按需更新）	高频字段、热点数据

4.3 版本前缀与命名空间隔离

版本前缀是命名空间的一种特殊形式，它允许同一领域实体在不同版本下共存。通过将版本号作为键名的前缀段，可以实现逻辑上的命名空间隔离。

  命名空间隔离示例：

  order:order:detail:v1:12345 → 旧版订单详情

  order:order:detail:v2:12345 → 新版订单详情（含折扣字段）

  两个键在 Redis 中独立存储，互不干扰。

版本前缀的扫描与清理：

# 扫描所有 v2 版本的订单详情键
SCAN 0 MATCH order:order:detail:v2:*

# 清理所有 v1 版本的过期数据
redis-cli --scan --pattern "order:order:detail:v1:*" | xargs redis-cli DEL

避坑提示：不要在生产环境使用 KEYS 命令扫描版本前缀，它会阻塞 Redis 单线程。始终使用 SCAN 命令进行游标式迭代。

4.4 版本化键的领域边界映射

在领域驱动设计中，缓存键的版本化设计需要与聚合根和值对象的边界对齐。每个聚合根应拥有独立的版本号，值对象则跟随所属聚合根的版本。

4.5 版本化键的读写契约

在代码层面，版本化键的生成应封装在缓存仓库（Cache Repository）中，业务逻辑层不直接拼接键名。以下是一个基于领域版本的键生成示例：

// 缓存仓库中的键生成方法
public class OrderCacheRepository {
    private static final String NAMESPACE = "order";
    private static final String ENTITY = "order:detail";
    private static final String VERSION = "v2";

    public String buildKey(Long orderId) {
        return String.format("%s:%s:%s:%d",
            NAMESPACE, ENTITY, VERSION, orderId);
    }

    public void saveOrderDetail(OrderDetail detail) {
        String key = buildKey(detail.getOrderId());
        redisTemplate.opsForValue().set(key, detail);
    }

    public OrderDetail getOrderDetail(Long orderId) {
        String key = buildKey(orderId);
        return redisTemplate.opsForValue().get(key);
    }
}

最佳实践：将版本号定义为常量或配置项，通过 CI/CD 管道在发布时自动更新。避免在代码中硬编码版本号，降低人为错误风险。

4.6 版本化键的演进策略

当领域模型发生向后不兼容的变更时（如字段删除、类型变更），需要执行版本迁移。推荐采用双写 + 双读策略：

双写阶段：同时写入旧版键（v1）和新版键（v2），确保数据一致性。
双读阶段：优先读取新版键，若不存在则回退到旧版键，并触发异步刷新。
旧版清理：确认新版稳定后，通过 SCAN 命令批量删除旧版键。

阶段	写入策略	读取策略	风险
双写	同时写 v1 和 v2	只读 v1	存储翻倍
双读	只写 v2	优先 v2，回退 v1	短暂回退延迟
清理	只写 v2	只读 v2	旧数据丢失风险

关键提醒：版本迁移期间，务必监控缓存命中率与回退率。若回退率超过 5%，应延长双读阶段，确保新版数据已充分预热。

4.7 版本化键的监控与治理

在 Redis 集群中，版本化键的治理需要配套键空间分析与版本分布监控：

键空间分析：使用 redis-cli --bigkeys 或自定义脚本统计各版本前缀的键数量与内存占用。
版本分布监控：通过 Prometheus + Grafana 采集各版本键的访问频率，识别过期版本。
自动化清理：设置 TTL 或定时任务，自动删除超过保留期的旧版本键。

# 统计各版本前缀的键数量
redis-cli --scan --pattern "order:order:detail:v1:*" | wc -l
redis-cli --scan --pattern "order:order:detail:v2:*" | wc -l

# 设置旧版本键的过期时间（批量）
redis-cli --scan --pattern "order:order:detail:v1:*" | while read key; do
    redis-cli expire "$key" 86400  # 24小时后过期
done

通过版本化键设计，缓存系统具备了契约版本感知能力，能够安全地支持领域模型的持续演进，避免因数据版本错乱导致的线上故障。