valkey-go广播模式与DoCache实战:PREFIX、BCAST与MGetCache的正确打开方式

原创2026-11-02 20:14:401,660 阅读

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 客户端缓存的最佳实践。

登录后查看全文
valkey-go