Go hash.Hash.Sum 怎样把摘要追加到已有缓冲区而不覆盖前缀

在 Go 里计算摘要时，最容易误读的不是哈希算法，而是 hash.Hash.Sum 的参数。它接收的不是“输出缓冲区”，而是一个要被保留的前缀：摘要会追加到这个切片的末尾。也就是说，想保留日志标签、协议头或复用中的字节，应该把前缀传给 Sum，不要先切一个看似足够大的空片段。

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

本文只讨论 dst 追加语义、切片长度与容量、哈希状态边界和缓冲区复用，不展开具体算法如何选。

先看 Sum 为什么不会覆盖已有前缀

把 Sum 想成“把摘要接到 b 后面”最准确。下面的 prefix 有两个字节，返回值会在它后面增加摘要；传入 nil 时，返回值则只包含摘要。

package main

import (
    "crypto/sha256"
    "fmt"
)

func main() {
    h := sha256.New()
    // Write 只改变当前哈希状态；错误不会由标准库哈希实现返回。
    _, _ = h.Write([]byte("hello"))

    prefix := []byte("id=")
    // Sum 会保留 prefix，并把当前摘要追加在它后面。
    result := h.Sum(prefix)

    fmt.Printf("prefix=%q len=%d\n", prefix, len(prefix))
    fmt.Printf("result=%x\n", result)
}

这里要注意一个细节：result 和 prefix 可能共享底层数组，但 result 的长度更长；因此打印 prefix 仍然只会看到它自己的前缀内容。这个行为适合把固定字段和摘要连续编码到一个字节切片中。

用 len、cap 和 Size 预测返回结果

如果哈希对象是 h，传入切片是 b，那么返回值的长度可以按下面的关系理解：

len(h.Sum(b)) = len(b) + h.Size()

Size 表示摘要占用的字节数，不是当前输入长度；len(b) 表示前缀已经有效的部分；cap(b) 决定实现是否有机会在原底层数组后面继续写入。不能只看容量就假设一定复用，也不能把扩容后的返回值忽略掉。

package main

import (
    "crypto/sha256"
    "fmt"
)

func main() {
    h := sha256.New()
    // 用固定输入说明 Size 与输入长度是两件事。
    _, _ = h.Write([]byte("payload"))

    prefix := make([]byte, 2, 2+ h.Size())
    copy(prefix, []byte("v1"))
    // 重要：必须接住返回值，Sum 可能返回新的底层数组。
    digest := h.Sum(prefix)

    fmt.Printf("size=%d prefix=%d result=%d\n", h.Size(), len(prefix), len(digest))
}

示例中的容量只是给出复用机会。若前缀长度是 2、摘要长度是 32，返回值长度就是 34。无论底层数组是否复用，调用方都应以后一次返回的切片为准。

把 Sum、Write 和 Reset 的职责分开

排查“连续计算结果不对”时，先把三个动作分开：

所以同一个哈希对象可以连续调用两次 Sum(nil)，得到相同的当前摘要；但如果两次之间调用了 Write，第二次摘要就对应更长的输入。把 Sum 当成“取出并清空”会让后续逻辑误判。

封装一个不会丢失返回值的追加函数

在日志或协议编码中，可以把“前缀 + 摘要”封装起来，并明确返回新切片。这样调用方不会误以为传入的切片已经被扩展到新长度。

package digest

import "hash"

// AppendSum 把当前摘要追加到 dst，并把扩展后的切片交还给调用方。
func AppendSum(dst []byte, h hash.Hash) []byte {
    // h.Sum 不改变状态；接住返回值才能兼容扩容和底层数组复用两种情况。
    return h.Sum(dst)
}

如果需要长期保存结果，建议再复制一份属于业务对象的切片，避免继续复用同一底层数组时产生别名影响。摘要内容本身也不应被当作加密或认证证明；真实安全需求要结合算法和协议完整设计。

常见误区与快速排查

• 把 Sum 当成覆盖写：实际它是追加写，前缀长度会保留。
• 只看 cap 不接返回值：扩容后旧切片仍然只有旧长度。
• 用输入长度推断摘要长度：应使用 h.Size()。
• 以为调用 Sum 会消费状态：它不会，状态变化来自 Write 或 Reset。

可以按“前缀长度、摘要长度、返回值长度、是否继续 Write”四项顺序排查。只要这四个值对得上，绝大多数“摘要覆盖前缀”或“第二次结果异常”问题都能定位。

相关问题

Sum(nil) 和 Sum([]byte{}) 有区别吗？

两者都表达“没有有效前缀”，返回结果都应从摘要开始；实际代码中可按是否需要复用已有切片来选择。

为什么必须接住 Sum 的返回值？

因为追加可能触发扩容，返回值才是包含完整摘要的切片；传入切片本身的长度不会自动变长。

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

可以。Sum 只读取当前状态，后续 Write 会在当前状态上继续吸收数据，下一次 Sum 得到新的摘要。

总结一下：把 hash.Hash.Sum 记成“向 dst 末尾追加当前摘要”，用 Size 计算结果长度，用返回值承接可能的扩容，再把 Write、Sum、Reset 的状态职责分开，缓冲区复用就不容易越界到错误的语义上。