签名验证不能只比对hmac.Sum256原始字节数组，因网络传输需base64或hex编码，客户端未编码或编码不一致会导致校验失败；必须统一编码、标准化原文、前置读取Body计算body_hash，再校验签名与时间戳。
签名验证为什么不能只比对 hmac.Sum256 的原始字节数组
因为网络传输中字节序列无法直接作为 HTTP Header 或 query 参数安全传递，必须编码。常见错误是直接用 hmac.Sum256([]byte(data)).Sum(nil) 得到的 []byte 去做字符串比较，结果永远失败——服务端解码后得到的是 base64 或 hex 编码串，而客户端没编码，或用了不同编码方式。
- 客户端签名后必须用
base64.StdEncoding.EncodeToString()（推荐）或hex.EncodeToString()编码，且服务端用完全相同的编码方式解码 - 注意：
base64.RawStdEncoding会省略填充符=，若前后端不一致会导致解码失败 - 签名原文必须严格约定顺序和格式，例如：
method|path|timestamp|nonce|body_hash，任意字段缺失或顺序错乱都会使签名失效
如何在 Gin 中统一拦截并校验 X-Signature 和 X-Timestamp
Gin 的中间件是最自然的切入点，但要注意时间戳防重放校验不能只依赖 time.Now().Unix() 简单比对——服务器与客户端时钟偏差、NTP 同步延迟都可能导致合法请求被拒。
- 允许最多 300 秒（5 分钟）偏差，用
abs(reqTimestamp - time.Now().Unix()) -
X-Nonce必须在 Redis 中做短时效去重（如 EX 300），防止同一签名被重复提交 - 签名原文中的
body_hash要求：GET 请求为空字符串；POST/PUT 请求先用io.ReadAll(c.Request.Body)读取原始 body，再计算sha256.Sum256()，**必须还原c.Request.Body为io.NopCloser(bytes.NewReader(bodyBytes))，否则后续绑定会失败**
crypto/hmac 签名时密钥处理的三个关键点
密钥不是越长越安全，也不是随便拼接字符串就行。Golang 的 hmac.New 对密钥长度敏感，且硬编码密钥极易泄露。
- 不要用
[]byte("my-secret-key")直接当 key——应从环境变量或 KMS 获取，并用[]byte(os.Getenv("API_SECRET"))动态加载 - 若密钥长度 > SHA256 块大小（64 字节），
hmac.New会先用 SHA256 hash 它；若太短，会补零。建议密钥固定为 32 字节（如用crypto/rand.Read生成）以避免隐式处理 - 签名前务必对原始数据做标准化：去除首尾空格、统一换行符为
/n、query 参数按 key 字典序排序并 url-encode，否则同样参数因格式差异导致签名不一致
func generateSignature(method, path, timestamp, nonce, bodyHash, secret string) string {
data := fmt.Sprintf("%s|%s|%s|%s|%s", method, path, timestamp, nonce, bodyHash)
key := []byte(secret)
h := hmac.New(sha256.New, key)
h.Write([]byte(data))
return base64.StdEncoding.EncodeToString(h.Sum(nil))
}
为什么不能把签名逻辑放在 BindJSON 之后
因为 c.BindJSON(&v) 会消费 c.Request.Body 流，再读就返回 EOF。签名验证必须在任何结构化解析之前完成，且需保留原始字节用于 body_hash 计算。
立即学习“go语言免费学习笔记（深入）”；
- 正确顺序：读 body → 计算 body_hash → 构造签名原文 → 校验
X-Signature→ 校验时间戳与 nonce → 最后才调BindJSON - 若使用
c.ShouldBindJSON，它内部也会尝试读 body，仍会冲突；必须显式控制 Body 读取时机 - 测试时容易忽略：用 curl 发送 JSON 时若漏掉
-H "Content-Type: application/json"，Gin 可能跳过 JSON 解析逻辑，但签名原文里的body_hash仍是按 JSON 算的，导致不匹配
签名验证真正难的不是算法本身，是前后端对「原始数据」定义的一致性、Body 流的生命周期管理、以及时间/nonce 这类状态协同机制的落地细节。少一个环节，线上就可能大面积 401。