Go项目集成Redis缓存必须解决连接池、超时控制、序列化、键设计和多级缓存协同五大硬点：PoolSize设20–50、MinIdleConns≥5、MaxConnAge=30分钟，初始化后调Ping验证；所有操作须用context.WithTimeout；结构体序列化统一用json且字段导出加tag；键需加前缀；多级缓存TTL需对齐防脏数据。
Go 项目里集成 Redis 缓存，不是“连上就行”，而是必须同步解决连接池、超时控制、序列化、键设计和多级缓存协同这五个硬点；否则高并发下掉帧、goroutine 泄漏、脏数据、穿透复现会集中爆发。
go-redis/v8 连接池配置不调优，压测必报 redis: connection pool timeout
默认 PoolSize=10、MinIdleConns=0 在 QPS > 300 的服务里根本撑不住，错误日志里不会直接说“连接不够”，而是卡在 redis: connection pool timeout —— 实际是排队等连接，不是 Redis 慢。
-
PoolSize建议设为runtime.NumCPU() * 6（20–50 区间），别盲目填 100+，Redis 单实例maxclients通常 ≤5000 -
MinIdleConns必须显式设（如 5），否则冷启动时每个请求都触发建连，首屏延迟高、日志刷满redis: dial tcp -
MaxConnAge=30*time.Minute强制老化长连接，防 NAT/SLB 单向断连后 conn 还以为活着 - 初始化后立刻跑
rdb.Ping(ctx).Err()，别等第一个Get才暴露连不通
所有 Redis 操作必须带 context.WithTimeout，禁用 context.Background()
HTTP handler 里传 context.Background() 给 rdb.Get，等于把 goroutine 生死交给 Redis 响应时间：它卡 5 秒，你的 handler 就卡 5 秒，监控看到的是 runtime.NumGoroutine() 暴涨、QPS 断崖下跌。
- 统一用
ctx, cancel := context.WithTimeout(r.Context(), 300*time.Millisecond)，300ms 是缓存场景合理上限 -
Set、Del、分布式锁写入也必须超时，否则锁假死会阻塞后续全部请求 - 别在包级变量里声明
var ctx = context.Background()—— 它没有 cancel 信号，不是“默认”，是“永生”
缓存未命中时的 redis.Nil 错误必须显式判断
rdb.Get(ctx, key).Result() 返回值语义容易被忽略：命中返回值，未命中返回 redis.Nil 错误（不是 nil 指针），不判断就直接解包，会导致空结构体、panic 或缓存写入无效数据。
立即学习“go语言免费学习笔记（深入）”；
- 正确写法：
val, err := rdb.Get(ctx, key).Result(); if errors.Is(err, redis.Nil) { /* 缓存穿透处理 */ } - 结构体字段没加
json:"xxx"tag，json.Marshal会序列化出零值，缓存写入的是空对象 - 终端手动执行
redis-cli TYPE key和TTL key，比只看 Go 日志更能定位问题（比如类型错成 hash 却用Get）
本地缓存不能用 sync.Map，L1 必须选 bigcache 或 go-cache
sync.Map 是线程安全哈希表，不是缓存：它没 TTL、不淘汰、无容量控制、无命中统计，更不会自动同步到 Redis。你手动 Store 一个值，其他 goroutine 可能因内存模型看不到更新；用 time.Now().Unix() 算过期，在容器里时钟漂移后 L1 就永远不清理。
- 真要本地缓存，选
bigcache（压测吞吐高 2–3 倍）或github.com/patrickmn/go-cache（支持回调、统计、TTL） -
bigcache必须显式设MaxEntries和OnRemove回调，否则内存无限增长且对象不释放给 GC - L1 的 TTL 必须 ≤ L2 的剩余 TTL：读取前先调
rdb.PTTL(key)获取 Redis 中 key 剩余时间，再动态传给l1.Set(key, val, shortTTL)
多级缓存真正的复杂点不在代码结构，而在时间窗口里的一致性博弈——L1 的 TTL、L2 的 TTL、DB 更新耗时，三者只要差 100ms，就可能暴露脏数据；这个窗口没法靠“加锁”完全消除，只能靠 TTL 对齐、写时失效、空值缓存和 singleflight 控制放大效应。
