直接用 redis.client 写缓存易出问题，因需手动处理键名拼接、序列化、空值穿透、过期分级、错误重试等，散落业务代码导致维护难、错误频发（如未判 redis.nil 或 json.unmarshal panic），且易引发连接泄漏、time_wait 爆表。
为什么直接用 redis.Client 写缓存逻辑容易出问题
因为缓存操作从来不是“set 一下、get 一下”就完事。你要处理键名拼接规则、序列化反序列化、空值穿透、过期时间分级、错误重试、连接池复用，甚至降级开关。一旦这些散落在业务代码里，改个过期策略就得 grep 十几个文件。
- 常见错误现象：
redis: nil错误反复出现，其实是没判err == redis.Nil就直接解包；json.Unmarshalpanic 因为没检查 value 是否为空字符串或null - 使用场景：用户信息查库前先查缓存、商品库存扣减带原子性校验、接口限流计数器需要 TTL 自动清理
- 参数差异：
Set(ctx, key, val, ttl)的val类型不统一（有时是 struct，有时是 []byte），不封装就会在每个调用点重复做json.Marshal - 性能影响：每次手动 new
redis.Options或复用错*redis.Client实例，导致连接泄漏或 TIME_WAIT 爆表
用外观模式组织缓存操作的最小可行结构
外观不是加一层 interface 就叫外观，核心是把「谁来调用」和「怎么调用底层」彻底隔离。你对外只暴露一个 Cache 结构体，它内部聚合 *redis.Client、序列化器、键生成器、错误处理器 —— 但使用者完全感知不到。
- 不要暴露
redis.Cmdable接口，业务层不该知道底层是 Redis 还是 Badger；如果哪天要切到内存缓存，只改外观内部，调用方零改动 -
Cache.Get(key string, dst interface{}) error必须接收指针，否则json.Unmarshal无法写入；传值进去只会静默失败 - 键名生成必须收口：
cache.keyBuilder.UserDetail(uid)而不是业务层拼"user:detail:" + strconv.Itoa(uid)，避免不一致和硬编码 - 示例：
err := cache.Get("user:123", &user) // ✅ 自动反序列化到 user 结构体 if errors.Is(err, cache.ErrKeyNotFound) { ... } // ✅ 统一错误类型，不是 redis.Nil
绕不开的三个坑：空值、并发、上下文传递
这三个问题不提前设计，封装就变成套壳，上线后照样半夜被报警叫醒。
- 空值穿透：查数据库返回 nil，你不能直接
cache.Set(key, nil, ttl)—— Redis 不存 nil，会当成空字符串存进去，下次 get 拿到 "" 再 json.Unmarshal 就 panic。正确做法是存一个哨兵值（如cache.NullSentinel），get 时识别并返回cache.ErrKeyNotFound - 并发击穿：多个 goroutine 同时查缓存未命中，一起打到 DB。外观里得内置单飞行（singleflight）：用
singleflight.Group.Do(key, fn)包住 DB 查询，确保同一 key 只有一个请求真正查库 - 上下文必须透传：所有方法第一个参数必须是
ctx context.Context，且内部调用redis.Client时必须用ctx，不能用context.Background()。否则超时控制、链路追踪全失效
什么时候该放弃外观，直接碰底层
外观的价值是降低认知负担，不是消灭复杂性。真遇到以下情况，别硬套外观，老老实实写底层调用更稳。
立即学习“go语言免费学习笔记（深入）”；
- 需要 pipeline 批量操作：
cache.GetMulti([]string{...})封装后性能反而比原生pipe.Exec()差 30%，因为多了序列化/反序列化开销 - 要用 Redis 特有命令：比如
redis.Client.ZRangeByScore做排行榜分页，外观很难抽象出通用接口，强行封装只会让调用方更难理解参数含义 - 对延迟极度敏感：某些风控场景要求 P99 *redis.Client 更可控
外观真正的边界感在于：它不解决所有问题，而是明确划出「80% 场景下你应该用它」和「剩下 20% 请打开源码看它怎么写的，然后绕过去」——后者恰恰说明封装成功了。
