签名前必须标准化请求体格式，包括json字段排序、无空格编码、表单键值排序拼接，并完整读取body后重建；密钥须为[]byte类型，签名结果推荐hex编码；验签中间件需首个执行且避免body被提前消费；头字段名须与客户端严格对齐。
签名前必须标准化请求体格式
Go 中签名失败最常见的原因是请求体格式不一致：比如 JSON 底层字段顺序不同、空格/换行存在差异、浮点数精度被隐式截断。签名必须基于确定性字节流，不能直接对 http.Request.Body 读两次（它是一次性流），也不能依赖 json.Marshal 的默认行为。
实操建议：
- 统一用
json.MarshalIndent或更稳妥的json.Compact处理原始结构体，确保无空格、无换行、键名排序固定（需提前按字典序排序字段或使用map[string]interface{}+ 手动排序） - 若请求体是表单（
application/x-www-form-urlencoded），先用url.ParseQuery解析，再按键名排序后拼接成key1=value1&key2=value2格式（注意 URL 编码一致性） - 签名前始终从
io.ReadCloser中完整读取一次 body 到[]byte，再用bytes.NewReader重建可复用的 body —— 否则下游中间件或 handler 会读不到数据
用 hmac.New 计算签名时别忽略密钥类型与编码
签名本质是 HMAC-SHA256 等算法对标准化后的请求体做摘要，但 Go 的 hmac.New 接收的是 []byte 类型密钥，而开发者常误传字符串字面量或 base64 编码后的密钥，导致服务端验签永远失败。
实操建议：
- 密钥应作为二进制密钥传入，例如：
hmac.New(sha256.New, []byte("my-secret-key"))；若密钥本身是 base64 字符串（如配置项），需先调用base64.StdEncoding.DecodeString - 签名结果推荐用 hex 编码（
fmt.Sprintf("%x", sum)），而非 base64 —— 更少出现 URL 不安全字符，也避免大小写混淆问题 - 不要在签名中混入时间戳、随机 nonce 等动态字段，除非双方约定且严格同步；否则验签时无法复现原始输入
验签中间件里要小心 Body 被提前消费
HTTP 中间件若在验签前调用了 r.ParseForm()、r.ParseMultipartForm() 或任何读取 body 的操作，会导致后续 handler 收到空 body，引发业务逻辑错误。这是 Go Web 开发中最隐蔽的坑之一。
实操建议：
- 验签中间件必须是第一个执行的中间件，且只用
io.ReadAll(r.Body)读一次，然后用io.NopCloser(bytes.NewReader(data))替换r.Body - 如果框架（如 Gin、Echo）已自动解析 form 或 multipart，需关闭其自动解析（如 Gin 设置
DisableAutoTransaction: true），改由你手动控制解析时机 - 验签失败时返回
http.StatusUnauthorized并立即中断，不要继续调用 next handler —— 避免敏感逻辑被绕过
签名头字段命名与传输需与客户端严格对齐
签名是否生效，往往卡在 HTTP 头字段名大小写、拼写、是否带前缀等细节上。Go 的 http.Header 对键名自动转为 Canonical MIME Header Key（如 X-Signature → X-Signature，但 x-signature 也会被归一化），但客户端可能发 X-Request-Signature 或 Signature，服务端没匹配就直接跳过。
实操建议：
- 明确约定一个 header key，比如
X-Signature，并在服务端用r.Header.Get("X-Signature")获取，不要尝试多种变体 - 签名值建议同时携带算法标识和签名，例如
hmac-sha256=abc123...，便于未来扩展算法；验签时先切分再判断算法类型 - 若客户端是 JavaScript（如 fetch），注意浏览器同源策略下自定义 header 可能触发 preflight，需后端响应
Access-Control-Allow-Headers
真正难的不是写对那几行 HMAC 代码，而是确保请求体字节流在签名、网络传输、服务端接收三个环节完全一致——哪怕多一个空格、少一个转义、错一次编码，验签就崩。每次对接新客户端，都得抓包比对原始 body 字节和签名输入字节是否完全相等。
