Go sha256.Hash 怎样复制中间摘要状态

在 Go 里做“同一段前缀、多个后缀”的 SHA-256 计算时，直接把一个 hash.Hash 变量赋给另一个变量并不能复制摘要状态。更稳妥的做法是把 sha256.New() 返回的哈希断言为 hash.Cloner，调用 Clone() 得到独立分支；如果只是查看当前摘要，则调用 Sum(nil)，它不会消耗原状态。

这篇只讨论 hash.Cloner、Sum 与中间状态复用。官方文档中的接口名是 hash.Hash，并不存在需要直接实例化的导出类型 sha256.Hash。

问题现场：公共前缀被重复写入

假设一个服务需要给同一份公共内容追加多个候选字段，例如为不同版本的请求串计算签名。朴素代码会为每个候选重新创建哈希并写入公共前缀：

package main

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

func digest(prefix, suffix string) string {
	h := sha256.New()
	// 公共前缀每次都会被重新写入，分支很多时会产生重复工作。
	_, _ = h.Write([]byte(prefix))
	_, _ = h.Write([]byte(suffix))
	return hex.EncodeToString(h.Sum(nil))
}

func main() {
	fmt.Println(digest("公共内容", "候选 A"))
	fmt.Println(digest("公共内容", "候选 B"))
}

这个写法在分支很少时足够清楚，但每个分支都要重新处理公共前缀。若前缀来自较大的文件、协议头或规范化后的长文本，就可以把“已经写到哪里”保存成中间状态，再从这个状态分叉。

根因：Hash 接口没有 Clone 方法

sha256.New() 的返回类型是 hash.Hash。hash.Hash 提供 Write、Sum、Reset、Size 和 BlockSize，但复制状态的能力单独放在 hash.Cloner 接口中。当前官方文档把 Cloner 标记为 Go 1.25.0 引入，它的核心形状是：

type Cloner interface {
	Hash
	Clone() (Cloner, error)
}

因此，不能写成 h.Clone()，除非静态类型本身就是 hash.Cloner。正确做法是对运行时对象做接口断言：

package main

import (
	"crypto/sha256"
	"errors"
	"fmt"
	"hash"
)

func branch(prefix string, suffixes ...string) error {
	base := sha256.New()
	// 先写入所有分支共享的内容，后面只复制这一刻的状态。
	if _, err := base.Write([]byte(prefix)); err != nil {
		return err
	}

	cloner, ok := base.(hash.Cloner)
	if !ok {
		return errors.New("当前哈希实现不支持状态克隆")
	}

	for _, suffix := range suffixes {
		branchHash, err := cloner.Clone()
		if err != nil {
			// Clone 可能报告运行时不支持，不能把错误当成空摘要继续算。
			return fmt.Errorf("复制摘要状态失败: %w", err)
		}
		if _, err := branchHash.Write([]byte(suffix)); err != nil {
			return fmt.Errorf("写入分支内容失败: %w", err)
		}
		fmt.Printf("%s: %x\n", suffix, branchHash.Sum(nil))
	}
	return nil
}

func main() {
	if err := branch("公共内容", "候选 A", "候选 B"); err != nil {
		panic(err)
	}
}

这里的关键不是复制接口变量，而是由实现返回一份“等价且独立”的哈希对象。分支写入不会回写到 base，下一次循环仍可以从同一个公共前缀继续克隆。

修复动作：克隆后只修改自己的分支

一个容易混淆的点是：克隆应当发生在公共前缀写完之后。若在写前缀之前克隆，得到的只是多个空状态；若在某个分支已经写入后继续复用该分支，则后续结果会把前一个后缀也带进去。

推荐把“基线状态”和“分支状态”分开命名，并让每次循环都从基线调用 Clone：

// base 只代表公共前缀；每个 branchHash 只代表一个候选分支。
base := sha256.New()
_, _ = base.Write([]byte("用户标识|请求路径|"))

cloner := base.(hash.Cloner)
for _, candidate := range candidates {
	branchHash, err := cloner.Clone()
	if err != nil {
		return err
	}
	// 后缀只写入当前分支，不能再次写回 base。
	_, _ = branchHash.Write([]byte(candidate))
	digest := branchHash.Sum(nil)
	_ = digest // 这里可以复制结果，或编码后交给签名逻辑。
}

如果代码把 cloner 传到多个 goroutine，还要自行保证调用方式安全。Clone 提供的是独立状态，不等于哈希对象自动成为并发安全对象；更简单的方案是每个任务在自己的 goroutine 内完成一次克隆和写入。

Sum 只是读取检查点，不会把摘要“取走”

Hash.Sum(b) 会把当前摘要追加到 b 并返回结果，官方接口说明明确指出它不会改变底层哈希状态。这使它适合做日志、缓存键或调试检查点，但要注意返回值的切片语义：它会复用或追加到传入的切片。

h := sha256.New()
// 注释说明检查点用途：读取摘要后仍继续向同一个状态写入。
_, _ = h.Write([]byte("第一段"))
checkpoint := append([]byte(nil), h.Sum(nil)...)

_, _ = h.Write([]byte("第二段"))
finalDigest := h.Sum(nil)

fmt.Printf("检查点=%x\n最终值=%x\n", checkpoint, finalDigest)

如果需要长期保存检查点，像上面这样复制返回的字节更直观；不要把一个可能随后被追加修改的底层切片当成不可变快照。若目标是继续计算另一条摘要路径，应优先用 Clone，而不是把 Sum 的输出误认为可恢复的内部状态。

遇到 Clone 错误时怎样处理

标准库哈希实现通常支持 hash.Cloner，但接口允许某些包装型实现到运行时才知道是否可克隆，因此 Clone 仍返回 error。程序不应忽略这个错误，也不应把空摘要当成降级结果。

可以按业务需要选择三种处理方式：

如果项目需要兼容没有 hash.Cloner 的旧 Go 版本，就不能直接依赖这个新接口。可以在升级后使用 Cloner；若必须保持旧版本，则应选择重新计算，或采用当时可用的二进制状态序列化方案，并单独评估状态中可能保留输入片段的安全影响。

复用边界：什么时候值得保留中间状态

状态克隆适合“公共前缀大、分支多、每个分支后缀短”的计算。它减少重复写入，但每个分支仍会占用一个独立的哈希对象，不能无限制地把大量分支同时保存在内存里。

最后可以按下面的清单做决定：

• 公共前缀是否确实比后缀更大？如果不是，直接重新计算可能更简单。
• 分支是否都从同一个明确的检查点开始？如果检查点不同，应建立多个基线。
• 是否把 base 和分支对象分开管理？不要循环复用同一个已写入后缀的对象。
• 是否检查了类型断言和 Clone 返回的错误？错误不能被静默吞掉。
• 是否需要长期保存摘要结果？保存 Sum 返回的副本，不要把哈希对象当作可序列化业务数据。

相关问题

sha256.New 返回的是 sha256.Hash 吗？

不是。它的公开签名是 func New() hash.Hash。文章标题里的“sha256.Hash”是开发者常用的口语说法，代码应围绕 hash.Hash 和 hash.Cloner 编写。

调用 Sum(nil) 后还可以继续 Write 吗？

可以。Sum 不改变底层哈希状态，后续写入仍会从原位置继续；需要保存检查点时，应复制返回的字节切片。

Clone 后的对象能和原对象同时写入吗？

可以把它们当作独立状态使用，但不要因此推断哈希对象具备并发安全保证。并发场景应让每个任务独占自己的对象，并通过业务层同步共享结果。