sync.map 适用于小流量、单机、qps 几百的幂等场景，但无自动过期、不跨进程；需用结构体缓存结果、定时清理、避免 key 污染，redis 需原子 setnx+ex，db 唯一索引为兜底。
用 sync.Map 做单机幂等，什么场景能用、什么情况会翻车
小流量、单机部署、QPS 不超过几百时，sync.Map 完全够用，比 Redis 更快、零依赖。但它不是万能胶——它不支持自动过期，也不跨进程。
- 指纹 key 推荐拼成：
"idempotent:" + method + ":" + path + ":" + clientID + ":" + idempotencyKey，避免不同接口 key 冲突 - 缓存值别存
bool，得是结构体：{status: "success", result: json.RawMessage, timestamp: time.Time}，否则“已存在”时你没法安全返回原始响应 - 写入前必须先
Load，命中就直接返回；没命中才执行业务逻辑，完成后必须Store，不能只靠 if 判断 - 自己配定时清理：比如每分钟扫一次
timestamp超过 10 分钟的项，或按需淘汰（如 map size > 10000 就删最老的 10%） - 别在 handler 里裸用
sync.Map—— 并发请求共享同一个 map 实例没问题，但 key 构造逻辑如果混了context或临时变量，容易污染
redis.Client.SetNX 必须带 NX 和 EX，拆成两条命令就是埋雷
用 Redis 做分布式幂等，核心就一条：原子性判断 + 自动过期。漏掉任一环节，轻则缓存爆满，重则服务雪崩。
- 绝对不要先
EXISTS再SET，中间有竞态窗口；也别SETNX后补EXPIRE，万一第二步失败，key 就永久卡住 - 正确姿势是：
rdb.Set(ctx, key, value, ttl).AddArgs("NX", "EX", "300")（v9 客户端），或直接用封装好的SetNX(ctx, key, value, ttl) -
TTL时间得大于接口最长耗时 + 网络抖动余量，比如支付回调可能卡 45 秒，TTL 至少设 60 秒 - value 别用空字符串，建议存客户端传的
X-Idempotency-Key或 trace_id，方便日志对齐和人工排查 - Redis 连接失败时不能 fallback 到“放行”，得返回
503 Service Unavailable，否则幂等语义就崩了
数据库唯一索引不是可选项，而是兜底铁律
所有中间层幂等控制都可能失效：缓存击穿、Redis 故障、客户端绕过 header、网络重传……DB 层才是最后一道不可绕过的防线。
- 订单表必须建联合唯一索引：
UNIQUE (user_id, idempotency_key)，不是为了“防重复”，而是让重复插入直接报错 - Go 里识别冲突要精准：
pgx.ErrCodeUniqueViolation（PostgreSQL）或mysql.MySQLError.Number == 1062（MySQL），别 catch 所有 error 后静默返回 success - 错误处理逻辑必须区分：“真失败”（如库存不足）要返回 400，“已存在”才返回 200 + 原始结果，否则前端会以为操作失败而反复重试
- 别把唯一索引当第一道关卡——它响应慢、压 DB、用户体验差，只做兜底，不能替代前置校验
幂等中间件怎么写才不污染业务代码
把 if checkIdempotent() != nil { return } 塞进每个 handler，不出两周就会变成维护噩梦。中间件不是加个装饰器就完事，关键在上下文透传和状态抽象。
- 幂等 key 构造逻辑必须独立封装，比如
idempotent.KeyFromRequest(c.Request, "order_create")，而不是在 middleware 里硬写一堆c.GetHeader和fmt.Sprintf - 校验结果要用明确状态码表达：
idempotent.StatusNew（首次）、idempotent.StatusAlreadyHandled（已成功）、idempotent.StatusProcessing（正在处理中），让上层决定是否跳过业务逻辑 - 缓存的
result必须是完整响应体（如 JSON 序列化后的map[string]interface{}），否则“已存在”时你没法原样返回，又得查 DB，失去幂等意义 - 别用闭包变量存幂等状态——Gin 的
c.Keys或自定义context.WithValue才是安全透传方式
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
