缓存键必须采用“服务名+业务域+版本号”三段式前缀,如"svc:user:v2:id:123",以避免多版本结构污染、反序列化失败及静默逻辑错误;本地缓存也需按版本分桶隔离。

缓存键必须带服务名+业务域+版本号三段式前缀
多个 API 版本(如 v1、v2)共用 Redis 时,若都用 "user:123" 这类裸键,v2 新增字段后写入的 JSON 可能被 v1 读取并反序列化失败,报 json: cannot unmarshal string into Go struct 或字段全零值。这不是 Redis 问题,是键没隔离导致的结构污染。
正确做法是强制三段式命名:"svc:user:v2:id:123"、"svc:order:v1:uid:456"。其中:
-
svc表示服务名,避免跨服务冲突(如auth-service和user-service都有 user 数据) -
v1/v2是结构版本号,每次新增/删改字段、调整嵌套层级时必须升级 -
id/uid是语义化中段,比纯数字更易运维(比如批量KEYS svc:user:v1:id:*清理)
别用 fmt.Sprintf("user_%s_v%d", id, version) 这种拼法——冒号分隔更利于 Redis 命令识别,也方便后续用 SCAN 按前缀匹配。
结构体字段变更时,旧版本缓存不能自动兼容
Go 的 json.Unmarshal 对缺失字段默认设零值,但对新增的非零默认字段(如 Active bool `json:"active"`),v1 客户端读 v2 写的缓存会把 Active 解成 false,造成逻辑错乱。它不会报错,而是静默出错。
立即学习“go语言免费学习笔记(深入)”;
应对方式只有两条硬规则:
- 所有结构体字段必须显式加
json:"field_name"tag,禁止依赖默认命名;导出字段名变更 = 结构不兼容 = 必须升版本号 - v1 缓存过期后,v2 写入的新数据绝不能被 v1 代码读取——靠键前缀隔离,而不是靠反序列化兜底
例如 v2 新增 UpdatedAt time.Time `json:"updated_at"`,v1 的 struct 里没有该字段,那 v1 就不该去读 svc:user:v2:id:123,而应只查 svc:user:v1:id:123。
多版本缓存共存时,删除操作必须按版本逐条清理
用户资料更新时,如果只删 "user:123",v1 和 v2 的缓存都还在,下次 v1 请求读到的是旧数据,v2 请求读到的是新数据,状态分裂。线上最常见误操作就是删 key 不带版本。
正确的清理逻辑是:
- 更新 DB 后,生成所有已知版本的完整键列表:
[]string{"svc:user:v1:id:123", "svc:user:v2:id:123"} - 用
rdb.Del(ctx, keys...)一次性删掉全部,避免中间状态残留 - 如果版本太多(如 v1–v5),可考虑用
SCAN MATCH svc:user:v*:id:123+DEL批量清理,但要注意 SCAN 不保证原子性,需加重试
别在业务代码里写 rdb.Del(ctx, "user:123") —— 这个键根本不存在,删了个寂寞。
本地缓存(sync.Map)也要按版本分桶,不能共享
如果用 sync.Map 做本地缓存,且多个 API 版本共用同一个 map 实例,v2 写入的结构体指针可能被 v1 读取后直接修改底层数据(尤其含 slice 或 map 字段时),导致数据污染或 panic。
安全做法是每个版本维护独立本地缓存实例:
localV1Cache *sync.MaplocalV2Cache *sync.Map
或者更统一:用 map[string]*sync.Map,key 为版本号,查缓存时先取对应版本的 map 实例再 Load。这样即使结构体字段不一致,内存层面也完全隔离。
容易忽略的一点:本地缓存的 key 也得带版本,比如 localV1Cache.Load("svc:user:v1:id:123"),否则 v1 和 v2 会互相覆盖同一内存地址。


















