hmac.New第二个参数必须是[]byte而非string；密钥类型错误、签名原文拼接不一致、body重复读取、timestamp与nonce校验不严是验签失败四大主因。
hmac.New 传 []byte 还是 string？密钥类型错就全崩
签名验签失败，八成栽在密钥类型上。Go 的 hmac.New 第二个参数必须是 []byte，不是 string——哪怕你写 []byte("secret") 都行，但绝不能用 string([]byte("secret")) 或隐式转换。
-
hmac.New(sha256.New, []byte("my-key"))✅ 安全、可复现 -
hmac.New(sha256.New, []byte(secretStr))✅ 只要secretStr是 string 类型变量，强制转没问题 -
hmac.New(sha256.New, []byte(string([]byte("x"))))❌ 多余转换，易引入空字符或编码歧义 - 用
string(secretBytes)再转回[]byte❌ 底层内存不共享，且可能含不可见控制符
实操建议：密钥统一从环境变量读取后直接 []byte(os.Getenv("API_SECRET"))，别中间多绕一环；测试时打印 len(key) 和 fmt.Printf("%q", key) 确认没空格/换行。
签名原文拼接顺序不对，hmac.Equal 永远返回 false
客户端和服务端算出的签名不一致，几乎全是拼接规则没对齐。不是“差不多就行”，而是每个字符、每个换行、大小写、URL 编码都得严丝合缝。
- 必须包含：
method+"\n"+path+"\n"+timestamp+"\n"+nonce+"\n"+bodyHash（推荐 SHA256(body) hex 小写） - query 参数不能用
req.URL.RawQuery—— 它顺序不定；得手动解析url.ParseQuery，再sort.Strings(keys)后拼key=value&key=value -
body要用原始字节流计算哈希，不是c.PostFormValue或c.ShouldBindJSON解析后的结构体 - 所有 value 必须做
url.PathEscape（不是url.QueryEscape），尤其含斜杠、空格、中文时
常见错误现象：X-Signature-Timestamp: 1711800000 （末尾带空格）、GET /api/v1/user 和 get /api/v1/user（method 大小写不一致）、body 里 JSON 字段顺序不同导致哈希不同。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
Gin 中间件里怎么读 body 才不丢数据？c.GetRawData() 是个坑
在 Gin 中间件里想验签就得读 body，但读完 c.ShouldBindJSON 就报 EOF —— 因为 Request.Body 是单次读取流，不缓存。
- 别用
c.GetRawData()：它只能调一次，且后续任何绑定（包括c.Request.Body）都会失败 - 正确做法：用
io.ReadAll(c.Request.Body)读出原始字节 → 计算签名 → 用io.NopCloser(bytes.NewReader(bodyBytes))重置c.Request.Body - 必须在
c.ShouldBindJSON或c.Bind之前做，否则绑定会提前消费 body - 如果只校验 query/header，body 不参与签名，那就完全不用碰 body，避免风险
使用场景：微服务间调用、支付回调、Webhook 接收，这些地方 body 往往是关键业务数据，必须原样参与签名计算。
防重放靠 timestamp 和 nonce，但光校验时间戳远远不够
只检查 timestamp 是否在 ±300 秒内，等于没防重放。攻击者截获一个合法请求，改个 nonce 再发一次，照样过。
-
timestamp校验只是第一道过滤：用time.Now().Unix()和请求里的值比，差值 > 300 就拒收 -
nonce必须全局唯一且短期有效：Redis 存SET nonce:abc123 "" EX 300，设 TTL 300 秒；失败则return 401 - 别用
sync.Map做 nonce 缓存：单机可用，多实例部署时完全失效 - nonce 生成要用
crypto/rand.Read生成 16 字节再 hex 编码，别用uuid.NewV4().String()（含连字符，长度不固定） - 验签前先检查
timestamp是否为纯数字字符串，否则strconv.ParseIntpanic
容易被忽略的地方：系统时间不同步。2026 年 3 月线上服务若和 NTP 服务器偏差超 5 秒，就会批量验签失败——上线前务必跑 ntpq -p 或 chronyc tracking 确认。
