Go服务端不做幂等控制必然导致重复写入，必须用redis.SetNX（带EX过期时间）首道拦截、拼业务上下文key、存trace_id为value、Redis故障返回503、DB唯一索引兜底。
Go 服务端不做幂等控制，重复请求一定会写多条数据——这不是概率问题，是确定性行为。HTTP 协议不保证一次只处理一个请求，框架（gin/echo/net/http）也不管这事，必须你在关键路径上卡住。
redis.SetNX 必须带 EX 过期时间，不能只设 key
常见错误现象：SetNX 成功后业务 panic 或网络中断，key 永远留在 Redis 里，后续所有重试都被拦截，用户看到“重复提交”但实际没成功。
- 必须用原子命令
SET key value EX seconds NX，不能拆成SETNX+EXPIRE两步，否则中间崩溃会导致 key 永久残留 - 过期时间建议设为业务最长处理耗时 + 安全余量（如支付类接口设
3600秒），太短会误判重试，太长堆积无效 key - Go-Redis v9 推荐直接调
rdb.SetNX(ctx, key, value, ttl)，它底层自动拼NX EX参数，别手写命令 - value 别存空字符串，建议填
trace_id或客户端传的X-Idempotency-Key，方便日志对齐
key 要拼业务上下文，不能裸用 X-Idempotency-Key
只用客户端 header 的 X-Idempotency-Key 作 key，会导致不同用户、不同订单复用同一 key，引发误拒或漏判。
- 推荐格式：
idempotent:{user_id}:{idempotencyKey}，更严谨可加业务类型：idempotent:pay:{user_id}:{idempotencyKey} - 从
c.Request.Header.Get("X-Idempotency-Key")取值，为空应直接拒绝，不默认生成 - 取到后必须正则校验格式，比如
^[a-zA-Z0-9_-]{12,64}$，防 Redis key 注入 - 别哈希整个请求 body——顺序、空格、gzip 编码都会导致哈希不一致；客户端可控的稳定标识才是可靠指纹
数据库唯一索引是兜底，不是主方案
Redis 校验只是第一道防线，它挡不住缓存击穿、集群故障、客户端绕过 header 等场景。
Golang Google Wire
下载
在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface
立即学习“go语言免费学习笔记（深入）”；
- 必须在 DB 层加联合唯一索引，例如：
UNIQUE INDEX idx_user_id_idempotency_key (user_id, idempotency_key) - 插入失败后，别直接抛错，要捕获
mysql.ErrDupEntry或pgx.ErrCodeUniqueViolation，再查一次 DB 确认是否真已存在 - 别在事务中间做幂等校验——DB 成功但 Redis 失败，下次请求因 key 存在被误拒；校验必须放在最外层入口
- 索引字段别选太宽的列（如全量 request body），会拖慢写性能；用客户端生成的短 key 最稳妥
context 透传幂等标识，别用闭包变量存
Gin/Echo 中间件若用局部变量或闭包存 idempotent_key，并发请求会互相覆盖，一个请求的 key 被另一个覆盖，校验完全失效。
- 中间件里解析完 header 后，必须通过
ctx = context.WithValue(ctx, "idempotent_key", key)绑定到 context - handler 里统一用
ctx.Value("idempotent_key")拿，而不是重新解析 header - Redis 故障时不能静默 fallback 到“放行”，得返回
503 Service Unavailable，否则幂等语义彻底崩塌 - 幂等结果缓存要分状态，别只存
success；至少区分pending/success/failed，否则正在执行中的请求会被误判为已失败
真正难的不是写几行 SetNX，而是把幂等逻辑嵌进请求生命周期里——从 header 解析、context 透传、Redis 校验、业务执行、DB 写入，到最终响应返回，每一步都可能断链。最容易被忽略的是：Redis 故障时的降级策略、DB 唯一索引冲突后的二次确认、以及幂等 key 中业务上下文的粒度选择。这些地方一旦松动，幂等就只剩名义。
