直接用 maphash 做分片会出错，因其默认使用运行时随机种子，导致不同进程或重启后哈希结果不一致；必须显式设置固定种子，且路由逻辑需抽离为版本化独立模块统一管理。
为什么直接用 hash/maphash 做分片会出错
很多刚上手的人会直接拿 maphash.hash 对 key 做哈希，再对节点数取模，结果发现不同进程、不同重启后槽位映射不一致。根本原因是 maphash 默认使用运行时随机种子，每次启动 hash 结果都变——这在分布式场景下完全不可接受。
必须显式设置固定种子：
h := maphash.New()
h.SetSeed(maphash.Seed{0x12345678, 0x9abcdef0}) // 固定 seed
h.Write([]byte(key))
slot := int(h.Sum64() % uint64(slotCount))
- seed 必须硬编码或从配置加载，不能依赖 runtime 随机值
- 仅靠取模分配在扩缩容时大量 key 失效，真实生产环境应改用一致性哈希或预分片哈希槽（如 Redis 的 16384 槽）
-
maphash是 Go 1.19+ 推荐的非加密哈希，比crypto/md5快一个数量级，且无安全风险
如何让多个 Go 进程共享同一套槽位路由逻辑
关键不是“怎么算”，而是“所有服务必须用同一套规则算”。常见错误是各服务自己实现一遍哈希逻辑，版本或参数稍有差异就导致 key 路由错乱。
推荐做法：抽离为独立模块 + 显式版本控制：
// cache/routing/v1/route.go
func SlotForKey(key string) int {
h := maphash.New()
h.SetSeed(maphash.Seed{0x12345678, 0x9abcdef0})
h.Write([]byte(key))
return int(h.Sum64() % 16384)
}
func NodeForSlot(slot int, nodes []string) string {
return nodes[slot%len(nodes)] // 简单模运算，仅用于 demo；生产建议用虚拟节点
}
- 把
cache/routing/v1作为 go module 单独发布，所有服务统一require cache/routing v1.0.0 - 升级路由逻辑时必须发新版本（如 v1.1.0），禁止修改已有 v1.x 版本代码
- 避免在路由层做 DNS 解析或服务发现——节点列表应由上层传入，保持路由纯函数特性
客户端直连 vs 代理层：Go 实现中哪个更可控
Go 生态里多数人倾向客户端直连（如用 redis-go 自己做 slot 路由），因为能绕过代理延迟、便于埋点和熔断。但代价是每个语言 SDK 都要重复实现槽路由、故障转移、重试策略。
如果你的缓存集群规模不大（
client := redis.NewClusterClient(&redis.ClusterOptions{
Addrs: []string{"node1:6379", "node2:6379"},
HashFunc: func(key string) uint32 {
return uint32(routing.SlotForKey(key)) // 复用上面定义的函数
},
})
- 注意
redis-go的HashFunc返回的是uint32，需确保你的槽总数 ≤ 2^32，16384 安全 - 不要在
HashFunc里做网络调用或锁操作，它会在每次命令前被高频调用 - 如果用了服务网格（如 Istio），代理层可能更省心——但 Go 客户端得关掉内置重试，避免重试叠加
扩缩容时如何最小化 key 迁移
单纯增减节点数并重新取模，会导致 ≈ (N−1)/N 的 key 位置变化。Redis Cluster 用的是哈希槽迁移（migrate slot），Go 客户端必须配合识别 ASK / MOVED 错误。
以 redis-go 为例，它自动处理 MOVED，但默认不处理 ASK（临时重定向）：
client := redis.NewClusterClient(&redis.ClusterOptions{
// ...
// 需显式开启 ASK 支持
MaxRedirects: 16,
})
- 迁移中节点返回
ASK slot ip:port时，客户端应临时把下一次请求发给目标节点，而不是刷新整个槽映射 - 真正的平滑扩容需要服务端支持槽状态查询（如
CLUSTER SLOTS），客户端定期拉取并缓存，避免每次请求都问 - Go 中别用全局变量存槽映射表——多 goroutine 并发更新容易 panic，用
sync.Map或带版本号的原子指针
槽路由看着简单，真正难的是所有环节对“同一个 key 必须落到同一个槽、同一个节点”这件事达成绝对共识。哪怕一个服务忘了设 seed，或某次部署漏掉了 routing module 升级，缓存命中率就会断崖下跌——这种问题往往凌晨三点才暴露。
