valkey-go广播模式与DoCache实战:PREFIX、BCAST与MGetCache的正确打开方式
valkey-go广播模式与DoCache实战:PREFIX、BCAST与MGetCache的正确打开方式
valkey-go 是一款高速 Go 语言 Valkey 客户端,其亮点是支持服务端辅助的客户端缓存(Client Side Caching)。本文带你快速掌握 DoCache、PREFIX、BCAST 广播模式与 MGetCache 的正确用法,让缓存失效不再踩坑。
🎯 为什么需要客户端缓存?
在 valkey-go 中,DoCache() 相当于"把一份 Valkey 副本搬进你的应用进程":首次读取会回源 Valkey,后续相同请求直接从本地内存返回,延迟更低、吞吐更高。官方基准测试显示,开启客户端缓存后,GET 的延迟与吞吐表现"如同应用内嵌了一台 Valkey 副本"(详见 README.md)。
关键点:
- 默认是 opt-in 模式:只有你显式调用
DoCache()的命令才会被缓存 - 响应可以是缓存命中,也可以来自服务端,用
IsCacheHit()判断(定义于 message.go)
🚀 DoCache 快速上手:单 key 缓存读取
使用 DoCache 只需三步:构造命令时加 .Cache() 标记、传入客户端 TTL、选择 DoCache():
// 第一次:回源 Valkey,IsCacheHit() == false
resp := client.DoCache(ctx, client.B().Get().Key("k1").Cache(), time.Minute)
// 第二次:命中本地缓存,IsCacheHit() == true
resp = client.DoCache(ctx, client.B().Get().Key("k1").Cache(), time.Minute)
💡 小贴士:
time.Minute是客户端侧 TTL,即使服务端没设置过期,本地缓存也会在此时间后失效- 用
resp.CacheTTL()查看剩余客户端 TTL(秒) DoCache()的实现入口在 client.go,底层缓存存储默认是 LRU(见 lru.go),每条连接默认 128 MiB,由 valkey.go 中的DefaultCacheBytes控制
批量场景可使用 DoMultiCache 配合 valkey.CT() 构造函数:
client.DoMultiCache(ctx,
valkey.CT(client.B().Get().Key("k1").Cache(), 1*time.Minute),
valkey.CT(client.B().Get().Key("k2").Cache(), 2*time.Minute))
📡 广播模式详解:PREFIX 与 BCAST 的配置方法
默认 opt-in 模式下,Valkey 只向"发起过 DoCache 的连接"发送失效通知。如果你希望所有连接的缓存都能被精确失效,就需要广播模式(Broadcast Mode)。
只需在 ClientOption.ClientTrackingOptions 中配置前缀和 BCAST 标志:
client, err := valkey.NewClient(valkey.ClientOption{
InitAddress: []string{"127.0.0.1:6379"},
ClientTrackingOptions: []string{"PREFIX", "prefix1:", "PREFIX", "prefix2:", "BCAST"},
})
⚠️ 最容易被忽视的坑:PREFIX 声明的前缀必须覆盖你所有 DoCache() 命令用到的 key。否则该 key 的客户端缓存不会被 Valkey 失效,你会读到"看起来正确、实则过期"的旧值。ClientTrackingOptions 会在连接建立时追加到 CLIENT TRACKING ON 命令中(见 valkey.go)。
| 配置项 | 作用 | 建议 |
|---|---|---|
PREFIX |
声明 key 前缀,让服务端按前缀精确推送失效通知 | 与业务 key 命名规范对齐 |
BCAST |
广播失效通知到所有连接,避免多连接间缓存不一致 | 多连接场景必开 |
OPTIN(默认) |
只缓存显式 DoCache 的命令 |
默认即可 |
官方 BCAST 行为的完整测试用例可参考 pipe_test.go 中的 TestClientSideCachingBCAST。
📦 MGetCache:批量缓存读取的正确姿势
一次要读很多 key?手动拼 MGET 会踩"跨 slot 不能同发"的坑(集群模式下)。valkey-go 提供了 MGetCache 和 JsonMGetCache 两个辅助函数,帮你自动按 slot 分组、只把缓存未命中的 key 发给服务端:
// 按 key 分组,仅未命中部分回源,返回 map[key]ValkeyMessage
vals, err := valkey.MGetCache(client, ctx, time.Minute, []string{"k1", "k2", "k3"})
fmt.Println(vals["k1"].ToString())
实现原理见 helper.go:MGetCache 会为每个 key 构造 GET ... CACHE 命令并交给 DoMultiCache 统一处理;JSON 场景使用 JsonMGetCache。如果客户端缓存被禁用(DisableCache),它会自动退化为普通的 MGet,行为安全。
🧪 验证缓存是否生效:IsCacheHit 与 CacheTTL
两个响应方法帮你确认一切按预期工作:
resp := client.DoCache(ctx, client.B().Get().Key("prefix1:1").Cache(), time.Minute)
fmt.Println(resp.IsCacheHit()) // 响应是否来自本地客户端缓存
fmt.Println(resp.CacheTTL()) // 客户端缓存剩余秒数
- 写入/删除 key 后,Valkey 会推送
invalidate通知,客户端自动清除对应缓存(失效接口定义于 cache.go 的CacheStore) - 开启 OpenTelemetry(valkeyotel/)后,还会自动上报
valkey_do_cache_hits/valkey_do_cache_miss指标,方便监控命中率
🛠 延伸阅读与相关模块
| 模块 | 说明 |
|---|---|
| cache.go | CacheStore 接口:客户端缓存的存储契约(Flight/Update/Delete) |
| helper.go | MGet、MGetCache、JsonMGetCache 等批量辅助函数 |
| lru.go | 默认 LRU 客户端缓存实现,支持 single-flight 防击穿 |
| valkeyaside/ | Cache-Aside 模式封装,配合数据库回源与负缓存防穿透 |
| valkeyotel/ | OpenTelemetry 指标与链路追踪集成 |
| valkeyhook/ | 拦截 DoCache/DoMultiCache 的 Hook 扩展点 |
📌 一句话总结:DoCache + .Cache() 标记开启本地缓存,PREFIX + BCAST 保证多连接失效一致性,MGetCache 优雅处理批量读取——三者组合就是 valkey-go 客户端缓存的最佳实践。