签名验证必须作为Gin中间件注册在Use()中，统一从Authorization头提取Signature参数，校验时间戳（UTC基准±300秒）、Redis原子去重nonce，并严格对齐HMAC-SHA256签名原文拼接与密钥编码。
签名验证逻辑必须放在 gin.HandlerFunc 中间件里
Gin 的认证插件本质是中间件，不能在路由 handler 里做签名校验——那样会漏掉未注册的路径或提前透传请求。签名验证必须在 gin.Engine.Use() 或 router.Group().Use() 中注册，确保所有匹配路由都经过校验。
常见错误是把签名解析写在某个具体 handler 里，结果 API 被绕过；或者用 router.Any() 拦截但没调用 c.Next()，导致后续 handler 不执行。
- 签名字段建议统一从
Authorizationheader 提取，格式如Signature key=xxx,sign=yyy,ts=zzz,nonce=aaa - 必须校验
ts时间戳（如 5 分钟内有效），否则重放攻击无法防御 -
nonce需存入 Redis 做去重，单机内存 map 无法应对多实例部署 - 签名原文拼接顺序必须固定：HTTP 方法 + 请求路径 + 查询字符串 + 请求体 SHA256（若允许空体，需显式计入
""）
hmac.NewSHA256 签名生成与验签要严格对齐
Go 标准库 hmac.NewSHA256 本身没问题，但容易踩坑的是密钥编码、原始消息构造和 Base64 编码方式不一致。服务端验签失败，90% 是因为客户端用 UTF-8 编码拼串而服务端用了其他编码，或 body 读取后未重置 c.Request.Body 导致后续 handler 读不到数据。
- 密钥必须用
[]byte(secretKey)，不能用string(secretKey)直接传给hmac.New（虽能编译但语义错） - 请求体需用
ioutil.ReadAll(c.Request.Body)一次性读完，再用io.NopCloser(bytes.NewReader(body))重新赋给c.Request.Body - 验签前先检查
Content-Type是否为application/json或application/x-www-form-urlencoded，非标准类型可跳过 body 签名（或按策略拒绝） - Base64 解码后的 sign 字段长度必须为 32 字节（SHA256 输出），否则直接返回 401
时间戳校验要考虑时区与系统时间漂移
用 time.Now().Unix() 和客户端传的 ts 做差值判断，看似简单，但实际部署中常因容器时区未同步、宿主机 NTP 未启用，导致几秒甚至几十秒偏差。单纯设成 ±300 秒窗口可能让合法请求被拒，或给攻击者留出重放窗口。
立即学习“go语言免费学习笔记（深入）”；
- 服务端应使用
time.Now().UTC().Unix()统一基准，禁止用本地时区 - 生产环境必须开启 NTP 同步（如
systemd-timesyncd或chrony），并在启动时加健康检查：若系统时间与 NTP 源偏差 > 2 秒，panic 退出 - 可选：在响应头中返回
X-Server-Time: 1717023456，方便前端对齐时间，但不用于校验逻辑 - 不要依赖客户端传的
ts做日志排序或业务逻辑，它只用于时效性判断
Redis nonce 去重必须带 TTL 且容忍网络超时
nonce 存 Redis 是防重放的核心，但若用 SETNX + 单独 EXPIRE，存在竞态：set 成功但 expire 失败，nonce 永久卡住。更糟的是 Redis 连接超时未处理，导致所有请求 500。
- 必须用
SET key value EX 300 NX原子操作，TTL 设为和时间戳窗口一致（如 300 秒） - Redis client 超时设为 ≤ 500ms，失败时记录 warn 日志并返回 503（不可用），而非 401（避免暴露校验逻辑）
- 如果 Redis 不可用，是否降级？建议配置开关：
auth.fallback_to_timestamp_only = true，仅校验 ts，不校验 nonce（需运营侧评估风险） - 注意 Redis key 命名空间，建议用
auth:nonce:{client_id}:{nonce}，避免不同租户冲突
authorization vs Authorization）、以及 Go http.Request 对某些特殊字符的自动解码。这些地方不写测试用例，上线必出问题。 
