hash(key) % len(nodes) 不是一致性哈希，因其将哈希空间强行折叠为离散桶，节点变动时约75%请求重映射、缓存雪崩；真一致性哈希必须映射到0～2³²−1环、用虚拟节点、顺时针查找且环只读+二分。

为什么 hash(key) % len(nodes) 不是一致性哈希

它根本不是一致性哈希，只是普通取模——节点从 4 台变 5 台时，约 75% 的请求会重映射，缓存命中率断崖下跌，DB QPS 翻倍。这不是调优问题，是数学结构错误：取模把哈希空间强行折叠成离散桶，完全违背“增一个节点只动约 1/N key”的单调性要求。

• 一致性哈希必须把节点和 key 都映射到 0～2^32-1 的环上，靠顺时针查找定位
• hash(key) % len(nodes) 没有环，没有虚拟节点，也没有回绕逻辑
• 哪怕换用 xxhash.Sum64 或 maphash.Sum64，只要最后一步是取模，就还是雪崩起点

该用哪个哈希函数：crc32.ChecksumIEEE 是唯一推荐

环坐标必须是 uint32、跨语言一致、零分配、低碰撞。crc32.ChecksumIEEE([]byte(key)) 天然满足所有条件：Go 标准库内置最优查表，Java/Python/JS 默认也用它，避免“同一 key 在不同服务落到不同节点”这类线上事故。

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

• ❌ crc32.Checksum([]byte(key), nil) 会 panic，必须传表或改用 ChecksumIEEE
• ❌ md5.Sum 或 sha256.Sum256：加密级哈希，慢、分配多、输出非 uint32
• ❌ hash/fnv.New32a()：无 seed 控制，易被恶意 key 扎堆攻击
• ❌ maphash.Hash：输出 uint64，截断或 mod 2^32 会引入偏差，不适用于环坐标

sort.Search 查环必须兜底三处边界

sort.Search 是查有序环的唯一推荐方式，但它不自动处理环形语义。漏掉任一兜底，运行时 panic 或返回空节点是常态。

• 环为空：len(ring) == 0 时必须提前返回，否则 sort.Search(0, ...) 返回 0，ring[0] panic
• key 哈希值比所有节点都大：sort.Search 返回 len(ring)，需手动回绕到 ring[0]
• 最终索引必须用 i % len(ring) 回绕，这是环结构的数学必然，不是妥协
• 环结构必须是 []uint32（不是 int32），否则负数会导致绕环异常

虚拟节点数设 20–60 个/物理节点就够了

不是越多越好。实测表明：每物理节点配 20–60 个虚拟节点，即可将负载标准差压到 ±5% 以内；超过 100 后，查找延迟从 ~20ns 涨到 ~80ns，CPU cache miss 率陡增，初始化耗时也明显上升。

• 虚拟节点名必须确定：crc32.ChecksumIEEE([]byte(nodeName + "-" + strconv.Itoa(i)))
• 禁止用 rand.Uint32() 或未设 seed 的 math/rand —— 多 goroutine 并发下极易出错
• 生成时别用 fmt.Sprintf 拼接，unsafe.String 或预分配 []byte 更快（QPS 过万时明显）
• 环添加完必须 sort.Slice(ring, func(i, j int) bool { return ring[i] 排序，确保升序

环结构一旦初始化完成，应视为只读。动态扩缩频繁时，别每改一次就全量重建环；小规模集群直接 reload 更稳，复杂点在于节点名必须稳定、虚拟节点哈希必须可复现、边界兜底不能少。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！