Go crypto.SignMessage 如何兼容自带哈希与外部哈希：Signer 升级和回退边界

同一套签名业务里，调用方经常同时遇到两类签名器：老接口只接收已经算好的摘要，新接口希望自己接收原始消息并完成哈希。Go 1.25 在 crypto 包里补上了 MessageSigner 和 SignMessage，让封装层可以优先使用“自带哈希”的实现，遇到传统 Signer 时再回退到旧调用方式。

crypto.SignMessage 的价值不是替你选择签名算法，而是把“是否支持自带哈希”的判断集中起来：支持 MessageSigner 就调用 MessageSigner.SignMessage，否则沿用 Signer.Sign。

Go 1.25 先改变了哪一层接口

旧代码通常直接围绕 crypto.Signer 写适配器。这个接口的 Sign 方法接收 digest，也就是调用方已经根据签名算法算好的摘要；参数里还带着随机源和可选参数。这样的设计兼容面很广，但封装层必须知道“原文该用哪个哈希函数、什么时候算摘要”。

Go 1.25 新增的 crypto.MessageSigner 把输入改成消息本身，并把哈希决策交给签名器。官方发布说明同时给出了 crypto.SignMessage 的兼容意图：它会尝试使用 MessageSigner.SignMessage，如果传入对象没有实现这个接口，就调用传统的 Signer.Sign。

因此，这次变化更像是“在旧接口上增加一条可选的消息级路径”，而不是废弃 Signer。已有的 RSA、ECDSA 或其他签名器不会因为升级到 Go 1.25 就自动改变行为。

为什么不能在调用方盲目重复计算摘要

问题出在输入语义不一样。传统 Signer.Sign 要的是 digest，而 MessageSigner.SignMessage 要的是原始 message。如果封装层先把消息算成摘要，再把摘要交给 SignMessage，签名器可能会把这段摘要当成普通消息再次哈希，最终得到的签名自然无法按预期验证。

相反，如果把原始消息直接传给只实现 Signer 的旧对象，旧实现会把它当成摘要处理，同样是错误的。兼容封装的关键只有一句：消息级入口接收原文，旧接口分支才负责把原文变成摘要。

package signcompat

import (
    "crypto"
    "crypto/sha256"
    "errors"
    "io"
)

func signMessage(
    signer crypto.Signer,
    rand io.Reader,
    message []byte,
    opts crypto.SignerOpts,
) ([]byte, error) {
    return crypto.SignMessage(signer, rand, message, opts)
}

func signLegacy(
    signer crypto.Signer,
    rand io.Reader,
    message []byte,
    opts crypto.SignerOpts,
) ([]byte, error) {
    digest := sha256.Sum256(message)
    return signer.Sign(rand, digest[:], opts)
}

上面的 signMessage 是推荐的入口：由标准库决定是否走 MessageSigner.SignMessage。signLegacy 只适合你已经明确知道对象是传统 Signer、并且签名算法约定使用 SHA-256 的场景。不要把 signLegacy 的摘要结果再传给消息级接口。

把兼容路径收进一个可测试的封装

工程里可以保留一个很薄的适配函数，让业务层只传原文。下面的封装不自行做类型断言，也不复制标准库的升级判断；这样可以避免未来接口语义变化时，项目里出现多份不一致的分支。

func SignPayload(
    signer crypto.Signer,
    rand io.Reader,
    payload []byte,
    opts crypto.SignerOpts,
) ([]byte, error) {
    if len(payload) == 0 {
        return nil, errors.New("empty payload")
    }
    return crypto.SignMessage(signer, rand, payload, opts)
}

这里的空消息判断是业务约束，不是 crypto.SignMessage 的通用要求；是否允许空消息，要按协议定义决定。真正需要验证的是两条路径的输入是否一致：实现了 MessageSigner 的对象收到原文，只有旧 Signer 才收到对应算法的摘要。

迁移时需要核对的兼容边界

确认 Go 版本和构建矩阵

crypto.MessageSigner 与 crypto.SignMessage 属于 Go 1.25 的 API。若项目仍要支持更早的 Go 版本，不能直接在公共包里引用它们；应先用构建约束、兼容分支或保持旧接口的适配层，等最低版本提升后再切换。

不要混用哈希约定

crypto.SignerOpts 仍然描述签名参数。迁移前要写清楚它代表的哈希算法，尤其是旧实现要求摘要而新实现接收原文时。验证代码也要使用同一算法和同一输入，不要只检查“返回了非空签名”。

错误仍然要原样向上传递

随机源不可读、签名器拒绝参数或底层密钥出错时，兼容函数应该返回错误，不要在回退分支里偷偷改成另一个算法。日志可以补充路径信息，但不要把密钥材料、原文或完整签名写进日志。

最小验证：分别证明升级和回退

测试至少覆盖两种对象：一个实现 MessageSigner 的对象，确认消息级方法被调用；一个只实现 Signer 的对象，确认兼容入口仍能走 Signer.Sign。测试替身可以只记录收到的字节并返回固定错误，重点是断言调用路径和输入形态。

不要用一个真实密钥测试就结束。真实签名能验证算法结果，却未必能证明封装没有把原文提前哈希。把“收到的原文”和“收到的摘要”作为测试观测值，才看得出兼容分支是否正确。

相关问题

MessageSigner 会取代 Signer 吗？

不会。它是可选的消息级能力，crypto.SignMessage 仍然保留对传统 Signer 的回退。

调用方还需要自己计算哈希吗？

使用 crypto.SignMessage 时不需要为消息级实现提前计算；只有明确调用旧 Signer.Sign 时，才按签名算法准备摘要。

如何判断迁移没有重复哈希？

用两个测试替身记录各自收到的字节：消息级实现应收到原文，旧实现应收到约定长度的摘要，并分别检查错误和验证结果。

小结

Go 1.25 的这组 API 把签名兼容问题收敛成一条清晰路径：业务层保留原始消息，优先交给 crypto.SignMessage；标准库发现对象实现了 MessageSigner 就调用消息级方法，否则回退到 Signer.Sign。迁移的重点不是改更多代码，而是把哈希责任、版本边界和测试观测点写清楚。