签名验证中间件必须在路由绑定前注册，正确做法是全局或分组调用router.Use()；需同步处理query、header和body，提前读取并重置body流；时间戳验证应设±5分钟容错窗口；密钥须通过闭包注入而非硬编码，并使用ConstantTimeCompare防时序攻击。
签名验证中间件必须在路由绑定前注册
Gin 的中间件执行顺序由 Use() 调用时机决定，如果在 engine.GET() 之后才调用 Use()，该中间件对这个路由完全不生效。常见错误是把签名验证逻辑写在某个 handler 里手动校验，结果漏掉其他接口或破坏统一鉴权语义。
正确做法是：在定义路由前，用 router.Use() 全局注册，或对特定分组使用 group.Use()：
router := gin.Default()
router.Use(SignatureMiddleware()) // ✅ 全局生效
v1 := router.Group("/api/v1")
v1.Use(SignatureMiddleware()) // ✅ 仅 v1 下路由生效
v1.GET("/user", GetUserHandler)
注意：SignatureMiddleware() 必须返回 gin.HandlerFunc 类型函数，不能直接传闭包或未包装的函数。
签名算法需同步处理 query、header 和 body
Gin 默认不自动读取并缓存请求体（c.Request.Body），一旦调用 c.ShouldBindJSON() 或 c.GetRawData()，原始 body 就被消耗一次，后续再读会得到空内容 —— 这会导致签名比对失败，因为参与签名的 body 和实际解析的 body 不一致。
立即学习“go语言免费学习笔记（深入）”；
解决方法是提前读取并重置 body：
- 调用
c.Request.Body前先用c.GetRawData()一次性读出原始字节 - 用
bytes.NewReader()和c.Request.Body = io.NopCloser()重置 body 流 - 签名计算时，按约定顺序拼接
method + path + query string + sorted headers + raw body
特别注意：Content-Type 和 X-Signature 这类关键 header 必须显式纳入签名字符串；query 参数需按 key 字典序排序并 url-encode，否则不同客户端生成签名不一致。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
时间戳验证必须做服务端本地时钟容错
签名中常含 X-Timestamp 头用于防重放，但直接用 time.Now().Unix() 和 header 时间戳做等值判断会因网络延迟、客户端时钟漂移而频繁失败。
应设置合理时间窗口（如 ±5 分钟），并统一用服务端时间计算：
ts, _ := strconv.ParseInt(c.GetHeader("X-Timestamp"), 10, 64)
now := time.Now().Unix()
if now-ts > 300 || ts-now > 300 {
c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "timestamp expired"})
return
}
不要依赖客户端传来的时区信息；所有时间戳统一视为 Unix 秒级整数，服务端不做任何时区转换。若业务要求更高精度，可改用毫秒级，但前后端必须严格对齐单位。
密钥管理不能硬编码在中间件函数里
把签名密钥（如 secretKey := "my-secret-123"）写死在 SignatureMiddleware() 函数体内，会导致无法切换环境（dev/staging/prod）、无法热更新、密钥泄露风险高。
推荐方式是通过闭包注入配置：
func SignatureMiddleware(secret string) gin.HandlerFunc {
return func(c *gin.Context) {
// 使用 secret 进行 HMAC 计算
mac := hmac.New(sha256.New, []byte(secret))
// ...
}
}
// 启动时从环境变量或配置中心加载
router.Use(SignatureMiddleware(os.Getenv("API_SECRET")))
更进一步，生产环境建议用 crypto/subtle.ConstantTimeCompare 替代 == 比较签名，防止时序攻击；同时记录非法签名请求的 IP 和 timestamp，便于事后审计 —— 这些细节不加，签名中间件只是个摆设。
