直接用 uuid 作为幂等键不行，因为幂等键必须由客户端提供并参与签名验证，服务端自动生成会导致相同请求携带不同键而无法识别重复；可靠幂等键需满足客户端可重放、服务端可校验、与请求内容强绑定。
为什么直接用 uuid 作为幂等键不行
很多同学一上来就用 uuid.New() 生成唯一 ID 当作幂等键，结果发现重复请求照样进业务逻辑。根本原因是：幂等键必须由客户端提供并参与签名验证，服务端不能自己生成——否则两次相同请求携带不同 idempotency-key，系统就无法识别它们是同一操作。
真正可靠的幂等键应满足三个条件：客户端可重放、服务端可校验、与请求内容强绑定。常见错误包括：time.Now().UnixNano() 生成键（时间精度高但不可重现）、rand.Intn()（完全不可控）、或只取 URL 路径忽略 query/body（导致 POST /order?user=1 和 POST /order?user=2 被视为同一操作）。
推荐做法是让客户端在请求头带 Idempotency-Key，服务端用该值 + 请求方法 + 路径 + 规范化 body（如 JSON 序列化后 sha256）拼接哈希，再存入 Redis 或本地 map 做存在性检查。
如何用 sync.Map 实现轻量级幂等缓存
开发阶段或低并发场景下，用 sync.Map 比接入 Redis 更快落地，但要注意它不支持 TTL，必须手动清理过期项，否则内存泄漏。
- 幂等键建议用
fmt.Sprintf("%s:%s:%x", method, path, sha256.Sum256(bodyBytes).Sum(nil))构造，避免纯客户端传的Idempotency-Key被恶意复用 - 写入前先
m.Load(key)判断是否已存在；若存在且状态为"success"，直接返回上次响应体（需提前序列化缓存） - 写入时用
m.Store(key, struct{ status string; resp []byte; ts time.Time }{...})，后续定时 goroutine 扫描ts超过 5 分钟的项并Delete - 不要用
sync.Map.Range()做全量扫描——高并发下性能差，改用单独 channel + ticker 控制清理节奏
gin 中间件里怎么安全提取和校验幂等键
在 gin.HandlerFunc 里直接读 c.Request.Header.Get("Idempotency-Key") 很危险：客户端可能传空、超长、含控制字符，或重复传多个同名 header。必须做前置过滤。
实操建议：
- 用
strings.TrimSpace()清除首尾空格，长度限制在 64 字符内（防止 DOS 攻击） - 拒绝包含
\n、\r、NULL字节的 key，否则可能绕过日志审计 - 对 body 提取前先调用
c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, 2 限流，防止大 payload 拖垮哈希计算 - 校验失败时统一返回
http.StatusPreconditionFailed（412），而不是 400，明确语义是“该操作已尝试过”
示例关键片段：
key := strings.TrimSpace(c.Request.Header.Get("Idempotency-Key"))
if len(key) == 0 || len(key) > 64 || strings.ContainsAny(key, "\x00\r\n") {
c.AbortWithStatusJSON(http.StatusPreconditionFailed, gin.H{"error": "invalid idempotency key"})
return
}
Redis 存储幂等状态时的原子性陷阱
用 SET key value EX 300 NX 看似能保证首次写入原子性，但实际会丢状态：如果服务在写入 Redis 后、执行业务逻辑前崩溃，该 key 就永远卡在 “已存在” 状态，后续所有重试都直接返回空响应，造成数据丢失。
正确方案必须分两阶段：
- 第一阶段：用
SET key "pending" EX 300 NX占位，成功则继续；失败说明已有 pending 或 success，此时要GET key查状态 - 第二阶段：业务逻辑成功后，用
SET key "success" EX 86400（长期保留结果），失败则DEL key释放锁 - 绝不能用
GETSET或INCR替代，它们无法区分 “第一次写入” 和 “覆盖旧值” - Redis 连接池要设足够大（至少 20+），否则幂等校验本身成瓶颈
容易被忽略的是：客户端重试间隔必须大于 Redis key 的 TTL，否则可能刚删掉 key，新请求又进来，重复执行业务逻辑。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
