Go maphash.Seed 为什么不能持久化到磁盘

在 Go 中，maphash.Seed 不能持久化到磁盘，不是因为文件格式不够好，而是它从设计上就代表“当前进程里选择哪一个随机哈希函数”。官方文档明确说明：Seed 只属于单个进程，不能序列化，也不能在另一个进程中重新创建。它适合保护内存哈希表、Bloom Filter 等派生结构，不适合充当跨重启的业务主键。

Seed 只保证进程内一致，不是磁盘配置

maphash.Hash 根据 Seed 和写入字节计算 64 位结果；两个 Hash 使用同一个 Seed 时，行为一致，使用不同 Seed 时通常会得到不同结果。这个一致性范围是刻意收窄的：Seed 用随机值选择具体哈希函数，让攻击者不容易预先构造大量碰撞值。

因此，h.Seed() 返回的是一个不透明的状态对象，而不是“算法版本 + 固定数字”。官方 API 只允许它来自 MakeSeed 或另一个 Hash 的 Seed，再交给 SetSeed 使用。零值 Seed 未初始化，传入 SetSeed 会触发 panic；把结构体硬编码、转成 JSON 或写成十六进制文本，都没有得到官方承诺的恢复方式。

为什么跨进程保存 Seed 会让分桶结果失效

假设服务把 maphash.String(seed, userID) % 16 当作内存分片编号，并把 seed 一并写入 checkpoint。服务重启后，即使业务输入完全没变，也不能把 checkpoint 中的内容还原成一个有效的 maphash.Seed。如果改为重新 MakeSeed，分桶编号会变化；如果把原始输入和旧分桶编号一起保存，又会把临时布局误当成事实，扩容或重建时更容易产生错配。

这也是为什么 maphash 文档把 Seed 描述为单进程值：它保证的是当前进程内多个计算者共享同一个哈希函数，而不是保证升级、重启、跨机器后的数值稳定。

需要持久化时保存输入，启动后重建派生结构

更稳妥的拆分是：数据库或文件保存用户 ID、规范化后的字符串，或者保存明确承诺稳定的摘要；启动时读取这些事实，再用新的 maphash.MakeSeed 重建内存 map、Bloom Filter 或分片索引。重建过程可以重复，持久层不依赖随机 Seed。

下面的示例把“跨进程键”和“进程内分桶”分开。SHA-256 摘要是稳定的 32 字节值；maphash 只负责本次进程的快速分桶：

package main

import (
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "hash/maphash"
)

// stableKey 生成可以写入文件或数据库的稳定键，不依赖 maphash 的随机 Seed。
func stableKey(input string) string {
    sum := sha256.Sum256([]byte(input))
    return hex.EncodeToString(sum[:])
}

// bucket 只服务当前进程的内存布局；重启后重新生成 seed 并重建即可。
func bucket(seed maphash.Seed, input string, buckets uint64) (uint64, error) {
    if buckets == 0 {
        return 0, fmt.Errorf("buckets must be greater than zero") // 避免对零取模
    }
    return maphash.String(seed, input) % buckets, nil
}

func main() {
    input := "tenant-42:user-7"
    seed := maphash.MakeSeed() // 每个进程自行生成，不写入持久层
    shard, err := bucket(seed, input, 16)
    if err != nil {
        panic(err)
    }
    fmt.Println(stableKey(input), shard)
}

落地前检查这三个边界

第一，若目标是密码学签名、去重指纹或跨语言协议，别把 maphash 当作安全摘要；官方文档明确说它不是密码学安全哈希。第二，若只是同一进程的 map 或 Bloom Filter，Seed 可以在多个 goroutine 间共享，但每个 goroutine 应使用自己的 Hash。第三，若必须让不同版本、不同机器得到同一分片，先定义规范化编码和稳定哈希算法，再为算法版本做迁移，而不是试图保存 Seed。

常见问题

为什么同一个输入重启后 Sum64 变了？

通常是因为新进程获得了新的 Seed。Sum64 同时依赖 Seed 和输入字节，输入不变不能推出结果不变。

能不能用 unsafe 取出 Seed 内部数字保存？

不建议也不应这样做。内部布局不是公共契约，可能随 Go 实现变化；这还绕过了 Seed 的进程边界设计。

保存 maphash 的结果是否就能恢复原来的分桶？

只能保存当时的结果，不能据此恢复 Seed。若分桶规则会变化，应保存原始键和算法版本，重建时重新计算。

判断标准很简单：需要跨进程复现，就保存规范化输入或稳定摘要；只需要当前进程内快速分布，就让 maphash.Seed 留在内存里。