Go crypto.Hash.New 怎样为已注册哈希算法创建摘要器

我在把多种摘要算法接到同一个文件指纹流程时，最容易混淆的是两个名字：crypto.Hash 不是正在计算的摘要器，它只是算法标识；crypto.Hash.New() 才会创建一次独立的 hash.Hash 状态。把这两个层次分开，动态选择算法就会清楚很多。

官方文档还规定了一个必须记住的边界：如果对应的哈希实现没有链接进当前二进制，直接调用 New() 会 panic。因此稳定写法是先调用 Available()，确认实现可用后再创建实例。

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

crypto.Hash 负责“选哪种算法”，hash.Hash 负责“保存这次计算到哪里”。先判断 Available()，再调用 New()，最后按需 Write 和 Sum。

先把算法标识和计算状态分开

crypto.Hash 是一个整数类型，用来标识 SHA-256、SHA-512 等哈希函数；它本身不保存已经写入的数据。每调用一次 New()，才会得到一个新的 hash.Hash，这个对象拥有自己的中间状态。

这一区分对并发和批处理很重要：多个文件要独立计算时，应该为每个文件创建独立实例，不能把同一个 hash.Hash 在多个任务间共享。

调用 New 前先判断 Available

Available() 报告指定哈希实现是否已经链接进二进制。标准库中，直接导入实现包通常会让该实现注册；如果算法包没有被导入，或者算法只有外部实现而当前程序没有接入，不能假设 New() 一定可用。

package main

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

func main() {
	// 直接引用 sha256 包，确保 SHA-256 实现被链接到程序。
	_ = sha256.New

	algorithm := crypto.SHA256
	if !algorithm.Available() {
		// 不可用时不要调用 New，否则官方契约允许它 panic。
		panic("SHA-256 implementation is not linked")
	}

	// New 创建的是本次计算专用的 hash.Hash 状态对象。
	hasher := algorithm.New()
	_, _ = hasher.Write([]byte("hello")) // hash.Hash.Write 按接口约定不会返回错误。
	digest := hasher.Sum(nil)             // Sum 会把摘要追加到 nil 切片并返回新结果。

	fmt.Println(algorithm, hasher.Size(), hex.EncodeToString(digest))
}

这里的 _ = sha256.New 是显式保留实现包引用的写法，也可以直接在业务代码中调用 sha256.New。关键不是写哪一行，而是不能只凭一个 crypto.Hash 常量就推断实现一定存在。

分段 Write，最后用 Sum 取结果

hash.Hash 是有状态的 io.Writer。同一段数据一次写入或分多次写入，摘要语义相同；这适合大文件、网络流和分块读取。Sum(b) 不会重置当前状态，而是把当前摘要追加到 b 后返回。

package digest

import (
	"crypto"
	"errors"
)

var ErrHashUnavailable = errors.New("hash implementation is unavailable")

func SumParts(algorithm crypto.Hash, parts ...[]byte) ([]byte, error) {
	// 先检查链接状态，把本来会 panic 的边界变成调用方可处理的错误。
	if !algorithm.Available() {
		return nil, ErrHashUnavailable
	}

	// 每次调用都创建新实例，避免不同请求共享中间状态。
	hasher := algorithm.New()
	for _, part := range parts {
		// hash.Hash.Write 的错误返回值按接口约定恒为 nil，这里只保留数据流。
		_, _ = hasher.Write(part)
	}

	// Sum 不改变 hasher；调用方仍可在这里继续 Write。
	return hasher.Sum(nil), nil
}

如果要把摘要追加到已有缓冲区，可以传入一个非空的 b；如果只需要独立摘要切片，传 nil 最直观。Size() 可以告诉你最终摘要长度，而且它本身不要求实现已经链接。

Available 为 false 时不要继续走 New

这条分支是本文最值得保留的工程规则。Available() 为 false 时，通常意味着当前程序没有包含该算法的实现；此时调用 New() 不是“返回一个空摘要器”，而是可能直接 panic。

把动态算法选择封装成稳定入口

当算法来自配置文件或协议字段时，不要把 crypto.Hash.New 散落在各处。统一入口可以集中处理不可用错误、分段写入和摘要返回，让上层只关心选择结果。

package digest

import "crypto"

func Digest(algorithm crypto.Hash, data []byte) ([]byte, error) {
	// 配置值可能指向未链接实现，先做可预期的错误分支。
	if !algorithm.Available() {
		return nil, ErrHashUnavailable
	}

	// New 返回独立状态；不要把它缓存成跨请求共享对象。
	hasher := algorithm.New()
	_, _ = hasher.Write(data)
	return hasher.Sum(nil), nil
}

如果配置层还要向用户展示算法名称，可以使用 algorithm.String()；如果要把它作为签名选项传入实现，HashFunc() 会返回自身。本文只把这两个方法作为接口关系补充，不把签名流程混入摘要函数。

Reset、重新 New 和 Sum 的取舍

短任务通常直接重新调用 New() 最清楚。需要在循环里复用对象时可以调用 Reset()，但必须保证上一次摘要已经被取出，且对象没有被其他 goroutine 使用。Sum 不改变状态，因此“取一次摘要后继续写”是允许的；如果要从零开始计算，仍然要 Reset()。

我的经验是：请求级代码优先重新 New()，生命周期很明确；只有在确实有大量短生命周期计算、并且已经明确对象不跨并发边界时，才考虑复用和 Reset()。这样更容易避免把上一份输入带进下一份摘要。

相关问题

crypto.Hash.New 返回的是同一个摘要器吗？

不是。每次调用都会创建新的 hash.Hash 状态对象；算法标识相同，不代表中间状态共享。

Available 为 false 时能不能先调用 Size？

可以。官方文档明确说明 Size() 不要求对应实现已经链接；但它只告诉你摘要长度，不会创建可写入的摘要器。

为什么不用具体包的 sha256.New？

如果算法固定，直接调用 sha256.New() 更简单。crypto.Hash.New() 适合算法由配置、协议或统一接口决定的场景，但必须保留 Available() 分支。

把整个流程记成一句话就够了：crypto.Hash 选算法，Available 守住链接边界，New 创建本次状态，Write 累积输入，Sum 取出结果。只要不把标识和实例混为一谈，动态哈希选择就不会变成隐蔽的 panic 来源。