Go hash.Hash 复用摘要对象时的 Reset 边界

复用 Go 的 hash.Hash 时，最重要的边界不是“何时调用 Sum”，而是“何时开始一条新的独立消息”。结论很明确：每条独立消息在第一次 Write 之前都应处于初始状态；如果对象刚处理过上一条消息，就先调用 Reset。Sum 只读取当前摘要，不会清空或改变底层状态。

我第一次给批量数据做摘要复用时，直觉上把 Sum(nil) 当成了“取结果并收尾”。测试单条输入完全正常，一换成循环，第二条结果就悄悄变成了前两条输入拼接后的摘要。这个问题不在 SHA-256，而在我误判了有状态对象的生命周期。

Go 官方接口文档：https://pkg.go.dev/hash#Hash

SHA-256 官方文档：https://pkg.go.dev/crypto/sha256

最先踩到的不是性能，而是状态串线

下面这段代码看起来像是在分别计算 A 和 B，实际第二个结果对应的是 A || B。因为第一次 Sum 后，Hash 仍然保留着 A 的运行状态，接下来的 Write 会继续累积。

package main

import (
    "crypto/sha256"
    "fmt"
)

func main() {
    h := sha256.New()

    _, _ = h.Write([]byte("A"))
    sumA := h.Sum(nil)

    // 错误边界：Sum 不会清空 A，下面写入的是 A 之后的 B。
    _, _ = h.Write([]byte("B"))
    sumB := h.Sum(nil)

    fmt.Printf("A: %x\n", sumA)
    fmt.Printf("A+B: %x\n", sumB)
}

如果业务含义是两条独立消息，就应在写入 B 之前调用 Reset。把它写在“新消息入口”比写在“旧消息出口”更容易审查，因为函数一开始就声明了自己的前置状态。

func digestInto(h hash.Hash, data []byte) [sha256.Size]byte {
    // 每次调用都从初始状态开始，避免上一条消息残留。
    h.Reset()
    _, _ = h.Write(data)

    // 复制到固定长度数组，调用方不会继续持有可复用缓冲区的别名。
    sum := h.Sum(nil)
    var out [sha256.Size]byte
    copy(out[:], sum)
    return out
}

hash.Hash.Write 的接口约定是不会返回错误，因此标准库哈希示例常忽略其错误值。若函数接收的是别的抽象或项目有统一错误处理规范，仍可按团队约定保留返回值处理。

Reset 应该放在前面还是后面

从接口语义看，只要下一条独立消息写入前完成重置，放在上一轮结尾或下一轮开头都能得到正确结果。但工程上我更偏向“入口重置”：调用者不必记住对象上一次如何退出，函数也不会依赖隐含的干净状态。

func digestMany(inputs [][]byte) [][sha256.Size]byte {
    h := sha256.New()
    results := make([][sha256.Size]byte, 0, len(inputs))

    for _, input := range inputs {
        // Reset 是独立消息的起点，不是 Sum 的副作用。
        h.Reset()
        _, _ = h.Write(input)

        raw := h.Sum(nil)
        var digest [sha256.Size]byte
        copy(digest[:], raw)
        results = append(results, digest)
    }
    return results
}

入口重置还有一个实际好处：以后即使循环体增加提前返回、条件分支或日志采样，下一轮的起点依旧清楚。相反，如果只在成功路径末尾重置，新增分支很容易绕开清理动作。

别忽略 Sum(b) 的“追加”语义

Sum(b) 不是把摘要写到 b 的开头，而是把当前摘要追加到 b 后面。传入 nil 会得到纯摘要；传入非空前缀，返回值会保留前缀再接摘要。

h := sha256.New()
_, _ = h.Write([]byte("payload"))

plain := h.Sum(nil)                    // 只有 32 字节摘要
tagged := h.Sum([]byte("sha256:"))    // 前缀后追加 32 字节摘要

fmt.Println(len(plain))   // sha256.Size
fmt.Println(len(tagged))  // 前缀长度 + sha256.Size

这也解释了为什么不能把 BlockSize() 当成输出长度。SHA-256 的摘要长度是 Size() 返回的 32 字节，而内部块大小是 64 字节。预分配结果时应使用 h.Size() 或具体算法常量 sha256.Size。

单次输入优先用 sha256.Sum256

如果输入已经是一整段 []byte，而且只计算一次，sha256.Sum256(data) 通常更直接。它返回固定长度数组，没有可复用状态，也就没有忘记 Reset 的机会。只有流式输入、多段 Write，或基准确认构造与分配值得关注时，才需要显式创建 hash.Hash。

用 benchmark 判断复用是否真的值得

性能案例最容易写成凭感觉的结论。这里不预设数字，因为编译器版本、输入大小、逃逸情况和调用方式都会改变结果。更可靠的做法是固定输入和输出消费方式，比较三种实现，并让 testing.B 报告 ns/op、B/op 与 allocs/op。

package digest_test

import (
    "crypto/sha256"
    "hash"
    "testing"
)

var benchmarkInput = []byte("stable benchmark payload")
var benchmarkSink [sha256.Size]byte

func BenchmarkSum256(b *testing.B) {
    for i := 0; i 

运行 go test -bench=. -benchmem -count=5。先看各组是否处理完全相同的输入并消费结果，再比较三个指标：ns/op 反映单次耗时，B/op 反映平均分配字节，allocs/op 反映平均分配次数。如果复用只让代码复杂，却没有在目标负载上形成稳定差异，就保留更简单的 Sum256 或每次构造。

并发场景的边界是独占，不是 Reset

Reset 只能恢复对象状态，不能让一个可变 Hash 自动变成并发安全。多个 goroutine 同时对同一实例执行 Write、Sum 或 Reset，输入边界会互相干扰，并可能产生数据竞争。最简单的方案是每个请求创建自己的 Hash；只有分配压力被基准证明后，才考虑 sync.Pool。

var sha256Pool = sync.Pool{
    New: func() any {
        return sha256.New()
    },
}

func digestPooled(data []byte) [sha256.Size]byte {
    h := sha256Pool.Get().(hash.Hash)

    // 借出期间由当前调用独占；入口重置隔离上一次使用。
    h.Reset()
    defer func() {
        // 归还前再次恢复初始状态，降低后续误用的认知负担。
        h.Reset()
        sha256Pool.Put(h)
    }()

    _, _ = h.Write(data)
    raw := h.Sum(nil)

    var out [sha256.Size]byte
    copy(out[:], raw)
    return out
}

sync.Pool 里的对象可能随时被运行时移除，所以它不是固定容量对象池，也不能承担持久资源管理。这里利用的只是“临时对象可能被复用”的语义。拿到 Hash 后由当前调用独占，结果复制完成后再归还；不要把借出的实例或依赖其内部缓冲区的切片泄漏给调用方。

Reset 不是安全擦除

Reset 的接口承诺是恢复到初始状态，适合划分逻辑消息边界；它没有承诺以防取证或防旁路分析的方式擦除内存。处理密钥、口令或其他敏感材料时，不要把调用 Reset 当作安全清除证明。摘要算法选择、密钥派生、MAC 使用和敏感数据生命周期，应按对应密码学 API 与威胁模型单独设计。

排查复用摘要错误的顺序

• 第二条开始错误：检查新消息第一次 Write 前是否 Reset；不要假设 Sum 会清空状态。
• 长度异常：检查是否把摘要追加到了非空切片，以及是否误用 BlockSize 作为摘要长度。
• 偶发错乱或竞态：检查同一个 Hash 是否被多个 goroutine 同时访问。
• 复用后仍有分配：检查 Sum(nil)、接口逃逸和结果复制方式，用 benchmark 数据定位，不要只看源码猜测。
• 对象池代码变复杂：重新比较 Sum256、每次 New 与 Pool；收益不稳定时回退到简单实现。

几个常见问题

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

可以。接口明确说明 Sum 不改变底层状态，后续 Write 会继续扩展同一条消息。这适合获取中间摘要，但不等于开始新消息。

Reset 应该在 Sum 前还是 Sum 后调用？

要先用 Sum 读取当前消息的摘要，再在下一条独立消息写入前 Reset。如果先 Reset，当前消息状态已经被丢弃。

每次 Reset 会改变哈希算法吗？

不会。它把当前实现恢复到该算法的初始状态，Size 和 BlockSize 等算法属性不变。

一个全局 Hash 加锁后能不能用？

只要锁覆盖 Reset、全部 Write、Sum 和结果复制，逻辑上可以串行化，但会形成共享热点，也容易因锁范围遗漏出错。通常每次新建或独占池对象更容易维护，是否优化仍应由基准决定。