hmac.New的key参数必须是[]byte，因为函数签名强制要求该类型；隐式转换string易引入BOM、空格等不可见字符，导致密钥不一致，正确做法是直接[]byte(os.Getenv("API_SECRET"))并打印len(key)和%q验证。
hmac.New 的 key 参数为什么必须是 []byte？
因为 Go 的 hmac.New 函数签名强制要求第二个参数是 []byte，不是 string。看似 string 能隐式转成 []byte，但中间一转换就容易混入 BOM、UTF-8 控制符、前后空格或换行——这些在肉眼和日志里几乎不可见，却会让密钥实际字节与服务端不一致。
- ✅ 正确写法：
hmac.New(sha256.New, []byte(os.Getenv("API_SECRET")))—— 环境变量直取、无中间转换 - ❌ 错误写法：
hmac.New(sha256.New, []byte(fmt.Sprintf("%s", secret)))——fmt.Sprintf可能引入空格或编码副作用 - ⚠️ 验证建议：验签失败时，立刻打印
len(key)和fmt.Printf("%q", key)，确认没多出\u0000、\ufeff或尾部空格
签名原文拼接顺序和编码方式怎么才和客户端对得上？
“差不多就行”是金融级接口验签失败的头号原因。哪怕一个字段大小写不对、一个空格位置不同、一个 url.QueryEscape 换成 url.PathEscape，hmac.Equal 就返回 false。
- 必须包含且顺序固定：
method（全大写，如"POST"）、path（不含 query，如"/api/v1/transfer"）、timestamp（秒级整数字符串，非毫秒）、nonce（客户端生成的随机字符串）、body_hash（sha256.Sum256(bodyBytes).Sum(nil)后 hex 小写编码） - query 参数不能用
req.URL.RawQuery—— 它顺序不保证；应url.ParseQuery()→sort.Strings(keys)→ 手动拼key=url.QueryEscape(value)→strings.Join(..., "&") - 所有 value 必须用
url.QueryEscape（空格变%20），不是strings.ReplaceAll，也不是url.PathEscape - 常见坑：
X-Signature-Timestamp: "1715234000 "（末尾空格）、GET /api?uid=123vsget /api?uid=123（method 大小写）、JSON body 字段顺序不同导致body_hash不同
验签中间件里 body 读取后怎么还原才能不影响后续绑定？
金融级接口常需校验 body_hash，但 c.Request.Body 是单次可读流。直接 io.ReadAll(c.Request.Body) 会耗尽它，后续 c.ShouldBindJSON() 或 c.PostForm() 全部失败。
- 必须在读取后还原：
bodyBytes, _ := io.ReadAll(c.Request.Body)→ 计算body_hash→ 再调用c.Request.Body = io.NopCloser(bytes.NewReader(bodyBytes)) - GET 请求的
body_hash应为空字符串，不能跳过赋值逻辑，否则拼接原文长度不一致 - 如果用了
c.Bind()类方法但没提前还原 Body，会静默绑定失败或 panic，而非报错提示
时间戳和 nonce 防重放为什么不能只靠内存缓存？
金融场景下，单机内存缓存无法应对集群部署、滚动更新、进程重启等现实问题，重放攻击窗口一旦打开就是真实资金风险。
立即学习“go语言免费学习笔记（深入）”；
-
timestamp校验必须允许合理偏差（如 ±300 秒），但偏差阈值要统一配置，不能硬编码在中间件里 -
nonce必须存 Redis，设置EX 300（5 分钟），且用SETNX原子写入；若已存在，立即拒绝，不走后续逻辑 - 不要用本地 map 或 sync.Map 存 nonce —— 多实例下完全失效，且 GC 后丢失
- 注意 Redis 连接超时或网络抖动时的 fallback 策略：宁可拒掉请求，也不能跳过防重放
