Go maphash.Hash.Clone 怎样复制当前哈希状态

当一段输入已经写入 maphash.Hash，但后面还要尝试多个不同后缀时，直接复制整个业务对象并不稳妥：复制哈希对象的内部状态需要由实现自己负责。Go 1.25 起，maphash.Hash.Clone 可以把当前状态复制成一个独立的 hash.Cloner，原对象和副本随后可以分别继续写入。

一句话结论：先把共同前缀写入原哈希，再调用 Clone；返回值可以继续使用 Write、Sum 和 Reset，对副本的追加不会改写原对象。官方文档地址：https://pkg.go.dev/hash/maphash#Hash.Clone

Clone 复制的是当前状态，不是重新创建一个空 Hash

maphash.Hash 不只是一个最后的整数。它包含随机种子、已经吸收的字节以及尚未完成内部处理的状态。Clone 的价值是把这些当前状态一起复制，让副本从同一个输入前缀继续计算。

例如，业务要分别计算 header|json 和 header|binary，共同部分 header| 只需要写入一次。复制完成后，原对象代表一个分支，副本代表另一个分支：

这和下面几种做法不同：

先看懂 hash.Cloner 返回值

Hash.Clone 的签名不是返回 *maphash.Hash，而是返回 hash.Cloner 和一个错误：

func (h *maphash.Hash) Clone() (hash.Cloner, error)

hash.Cloner 嵌入了 hash.Hash，所以它至少能继续执行 Write、Sum、Reset 等通用哈希操作，同时还保留 Clone 能力。使用接口值的好处是调用方不需要依赖具体哈希实现的内部字段。

如果代码只需要比较或保存摘要结果，直接使用接口就够了；不要为了读取未导出的内部状态去做反射，也不要把 maphash 的值当作可序列化配置。

从共同前缀复制出两个独立分支

下面的例子把同一个请求头作为共同前缀，然后让原对象和副本分别追加不同的后缀。代码只展示调用关系，不依赖本地运行结果。

package main

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

func main() {
	var base maphash.Hash
	base.SetSeed(maphash.MakeSeed())
	base.WriteString("header|") // 共同前缀只写入一次

	branch, err := base.Clone()
	if err != nil {
		// Clone 的错误必须保留给调用方，不能把空副本当成成功结果。
		panic(err)
	}

	base.WriteString("json")   // 原对象走 JSON 分支
	branch.Write([]byte("binary")) // 副本走二进制分支

	left := base.Sum(nil)
	right := branch.Sum(nil)
	fmt.Println(hex.EncodeToString(left))
	fmt.Println(hex.EncodeToString(right))
}

这个例子有三个关键点：

• Clone 发生在共同前缀写入之后，副本因此拥有相同的中间状态。
• base 和 branch 后续分别写入不同后缀，二者不会互相覆盖。
• Sum(nil) 读取当前摘要但不重置状态；如果还要继续追加数据，仍可继续调用 Write。

为什么原对象和副本可以各自继续写

hash.Cloner 的语义是返回一个“等价且独立”的状态。等价指的是 Clone 瞬间，副本和原对象看到相同的种子与输入序列；独立指的是 Clone 之后，对其中一个对象追加数据、调用 Reset 或读取摘要，不应改变另一个对象的状态。

因此，下面的顺序是有意义的：

// 共同输入：两个状态都应该包含它
base.WriteString("tenant|resource|")

// 在分叉点复制当前状态
branch, err := base.Clone()
if err != nil {
	// 生产代码可返回错误或记录失败原因，不要静默继续。
	return err
}

// 分叉后的写入只影响各自对象
_, _ = base.Write([]byte("read"))
_, _ = branch.Write([]byte("write"))

如果先给 base 写入 read，再 Clone，那么副本也会从包含 read 的状态开始。想让两个分支真正只共享 tenant|resource|，必须把 Clone 放在两个后缀之前。

Clone 的错误、版本和并发边界

1. 不要忽略错误返回值

标准库的 maphash.Hash 在正常配置下应能完成 Clone，但接口设计仍然保留了错误返回值。通用代码面对的是 hash.Cloner，某些包装实现可能只能在运行时判断是否支持克隆；遇到错误时应停止使用该副本，并保留原对象的处理路径。

2. API 版本要对齐

官方文档将 maphash.Hash.Clone 和 hash.Cloner 标记为 Go 1.25 引入的能力。如果项目的 go.mod 或构建工具链低于这个 API 所在版本，源码会在编译阶段失败。兼容旧工具链时，只能重放共同前缀，或者使用项目已有的状态保存方案，不能把 Clone 名称当成普通业务函数自行补出来。

3. Clone 不是并发锁

maphash.Hash 本身不支持多个 goroutine 并发使用。Clone 调用期间也不能让另一个 goroutine 同时对同一个源对象执行 Write、Reset 或 Sum。正确的并发模型是：在单 goroutine 中完成分叉，然后把各自独立的状态交给不同执行单元；如果只是要让多个对象使用同一个哈希函数种子，可以通过 Seed 和 SetSeed 分别初始化，但每个 Hash 仍要独立使用。

Clone、SetSeed 和 Reset 怎么选

常见问题

Clone 后调用 Sum 会消耗副本吗？

不会。Sum 读取当前状态并把结果追加到目标切片，不会像读取流那样把 Hash 清空；需要从初始状态重新计算时应显式调用 Reset。

能不能直接把 maphash.Hash 结构体赋值复制？

不建议把结构体赋值当成 Clone 的替代方案。哈希实现的内部布局属于实现细节，官方提供 Clone 就是为了表达“复制当前状态且副本独立”的稳定语义；代码应调用公开方法。

Clone 能不能把哈希状态保存到磁盘，之后再恢复？

不能据此推导出跨进程持久化能力。maphash.Seed 只在单个进程内有效，文章中的 Clone 也只解决当前进程中状态分支问题；需要持久化摘要时应保存最终结果或重新设计可复现的输入协议。

总结

Go maphash.Hash.Clone 的核心用途是把“已经写入共同前缀的中间状态”复制成独立分支。调用时记住四点：在分叉点之前写完共同输入；处理 hash.Cloner 和错误返回；分别使用原对象与副本；不要把 Clone 当作并发同步或跨进程持久化机制。