Go hash.Hash流式计算文件摘要并处理读取错误的实现方案

计算大文件摘要时，最稳妥的做法不是先用 os.ReadFile 把内容全部装进内存，而是让文件按块读取，把每块字节写入实现了 hash.Hash 的哈希对象。真正容易出错的地方在读取循环：一次 Read 可能同时返回有效字节和错误，必须先处理 n，再判断 err。这样既能控制内存，也不会漏掉最后一块数据。

Go 文件摘要的流式数据路径怎么安排

标准库的 hash.Hash 同时具备 io.Writer 能力。以 sha256.New() 为例，它不关心文件来自哪里，只接收连续的字节；文件则通过 io.Reader 提供数据。中间使用 32 KiB 缓冲区，内存占用不会随着文件大小线性增长。

实现时先打开文件并保证关闭，再创建哈希对象。每轮只把本次读到的 buf[:n] 写进去，不能把整个缓冲区都写入，否则最后一次不足缓冲区长度时会把旧数据一起算进去。

读取循环要先处理 n，再判断 err

下面的函数返回十六进制摘要和错误。代码没有依赖 io.Copy，是为了把部分读取的边界写清楚；如果你更偏好组合接口，也可以把哈希对象直接作为 io.Copy 的目标。

package digest

import (
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "hash"
    "io"
    "os"
)

func FileSHA256(path string) (string, error) {
    // Open 失败时直接返回，避免对空文件句柄调用 Close。
    file, err := os.Open(path)
    if err != nil {
        return "", fmt.Errorf("open %s: %w", path, err)
    }
    defer file.Close()

    var h hash.Hash = sha256.New()
    buf := make([]byte, 32*1024) // 固定缓冲区，内存不随文件大小增长。
    for {
        n, readErr := file.Read(buf)
        if n > 0 {
            // Reader 可能同时给出数据和错误，先处理有效字节。
            if _, writeErr := h.Write(buf[:n]); writeErr != nil {
                return "", fmt.Errorf("hash %s: %w", path, writeErr)
            }
        }
        if readErr == io.EOF {
            break // EOF 表示正常读完，不把它当成失败。
        }
        if readErr != nil {
            return "", fmt.Errorf("read %s: %w", path, readErr)
        }
    }

    // Sum 不会改变 h 的状态；编码只负责把摘要字节转成可比较的文本。
    return hex.EncodeToString(h.Sum(nil)), nil
}

这里把 hash.Hash 写成接口变量，是为了突出职责边界：换成 SHA-1、SHA-512 或其他实现时，文件循环不需要改变。实际安全场景应按业务要求选择算法，文件完整性校验和抗碰撞安全不是同一件事。

读取错误和摘要输出要分开判断

io.Reader 的约定允许一次读取返回 n>0 和非空错误，所以“看到错误就立即返回”并不严谨。上面的循环先写入有效字节，再把 io.EOF 解释为正常结束；其他错误则带上文件路径返回，调用方可以用 errors.Is 或 errors.As 继续判断。

如果使用 io.Copy(h, file)，它会读取到 EOF，并把第一个非 EOF 错误返回给调用方。这个写法更短，但手写循环更适合需要统计分块数量、记录进度或对单块数据做额外检查的场景。

大文件、空文件和哈希复用的边界

空文件会直接得到算法对应的空输入摘要，这是正常结果，不应当被当成读取失败。大文件的核心收益是固定缓冲区；如果把 io.ReadAll 放回实现中，摘要算法本身仍然正确，但失去了流式读取的内存优势。

同一个哈希对象复用前必须调用 Reset，否则第二个文件会接着第一个文件继续计算。并发场景下不要让多个 goroutine 同时写同一个 hash.Hash；每个任务创建自己的实例更直观，也避免摘要边界互相污染。最后，defer file.Close() 负责资源释放，但如果业务必须记录关闭失败，可以在命名返回值或显式收尾逻辑中单独处理。

相关问题

为什么不能直接对整个文件调用 hash.Write？

可以写入，但通常需要先把完整文件读入内存；流式写入能把内存上限稳定在缓冲区附近。

Read 返回 EOF 时一定没有数据吗？

不一定。一次读取可能同时返回 n>0 和 EOF，所以要先处理这 n 个字节。

Sum 调用后还需要 Reset 吗？

如果准备复用同一个哈希对象计算下一份独立数据，需要显式调用 Reset；只读取结果则不需要。