hash/maphash 如何为进程内哈希创建稳定的 Hash.Hash

如果你想让进程内的多个组件对同一字符串得到一致的 maphash.Hash 结果，关键不是保存一次 Sum64()，而是保存同一个 maphash.Seed。每次计算创建新的 Hash，调用 SetSeed 注入这枚 Seed，再以相同顺序写入字节即可。这样能保证同一进程内的分桶键、布隆过滤器或自定义哈希表使用同一套哈希函数。

这里的“稳定”有明确边界：Seed 只属于当前进程，不能序列化后在另一个进程恢复；Hash 也不能被多个 goroutine 同时复用。

先把 maphash 的稳定范围定清楚

maphash 的 Seed 选择具体的哈希函数。两个 Hash 使用同一个 Seed，并且收到相同的字节序列，就会得到相同的哈希值；换 Seed 后，结果很可能不同。零值 Hash 可以直接使用，但它会自行选择随机 Seed，多个调用之间不能依靠这个零值获得一致结果。

因此需要把需求拆成两种：进程内的多个 Hash 是否使用相同规则，以及结果是否需要跨进程复现。前者用 Seed 解决，后者不能用 maphash 的 Seed 解决。官方文档还明确说明，maphash 不是密码学安全哈希；如果结果要长期落库或用于签名，应选用有明确跨环境契约的编码或摘要算法。

用一个小型分桶工具创建稳定 Hash.Hash

下面的示例把 Seed 放在进程级对象中，再为每次字符串计算创建独立 Hash。它适合内存分桶、临时索引和同一进程里的多个组件协作。

package main

import (
	"fmt"
	"hash/maphash"
)

// processSeed 只在当前进程初始化一次，不能写入文件后跨进程恢复。
var processSeed = maphash.MakeSeed()

func stableHash(text string) uint64 {
	var h maphash.Hash
	// 每次调用使用独立 Hash，避免把可变的哈希状态交给多个调用共享。
	h.SetSeed(processSeed)
	// WriteString 的输入顺序就是哈希输入顺序；该方法不会返回写入失败。
	_, _ = h.WriteString(text)
	return h.Sum64()
}

func main() {
	// 相同 Seed 与相同字符串，在当前进程内得到相同结果。
	fmt.Println(stableHash("order:1001") == stableHash("order:1001"))
}

这个写法的“稳定”来自输入条件一致，而不是 Sum64 永远固定。程序重启后重新调用 MakeSeed，同一字符串通常会换一个结果；这正是它适合抵抗可预测碰撞、却不适合生成持久化哈希键的原因。

并发和复用时只共享 Seed

官方契约允许多个 goroutine 使用同一枚 Seed，但不允许多个 goroutine 同时操作一个 Hash。工程上可以把 Seed 作为只读配置传入 worker，每个 worker 在自己的调用栈中声明 Hash；如果一个 worker 连续处理多条数据，则可以调用 Reset 清空输入，Seed 会保留。

用检查清单避免把结果用错

1. 哈希输入是否有固定编码？字符串、字节切片和字段拼接必须保持同一顺序；必要时给可变长度字段增加明确分隔。
2. 是否把 Hash 当作持久化 ID？如果需要重启后不变，改用明确规定编码和版本的方案，不要保存 maphash 的 Seed。
3. 是否在 SetSeed 后才写入数据？该调用会丢弃之前的输入，初始化顺序应固定。
4. 是否把同一个 Hash 传给多个 goroutine？改为共享 Seed，在每个 goroutine 内创建 Hash。

常见问题

重新启动程序后还能得到同一个 Sum64 吗？

不能把它当作保证。新进程通常会生成新的 Seed；如果必须跨重启一致，应选择有稳定序列化契约的方案。

可以把 Seed 放进 JSON 配置吗？

不可以。Seed 是进程本地值，官方定义不支持序列化或在另一个进程重建。

只想快速计算字符串还需要显式创建 Hash 吗？

可以直接使用 maphash.String(seed, text)；当需要连续写入多个字段或实现 hash.Hash 接口时，再使用 Hash 对象。

结论可以浓缩成一句话：进程内一致性保存 Seed，计算状态保持 Hash 独立；跨进程稳定性和密码学摘要则交给专门设计的方案。