go接口幂等性核心是后端原子识别重复操作，需以redis.setnx（带nx+ex）为第一道防线，key须拼业务上下文如"idempotent:{business_type}:{user_id}:{idempotencykey}"，value存traceid，redis故障必须返回503，db唯一索引为兜底铁律。
Go 接口幂等性不是靠“前端防连点”或“文档约定”撑起来的，核心是后端能原子识别并拦截「同一业务操作的重复执行」。最稳的第一道防线是 redis.SetNX 配合业务上下文构造的 key 和明确过期时间，但必须搭配状态机与数据库唯一索引兜底——漏掉任一环节，线上就可能出现重复扣款、双发券、订单裂变。
为什么不能只用 X-Idempotency-Key 做 key
裸用客户端传的 header 值作 Redis key，会导致跨用户/跨接口污染或漏判。比如两个不同用户的请求都带 X-Idempotency-Key: abc123，一个被拒，另一个也跟着失败；或者同一笔转账因前端重试生成了两个不同 key，全被放行。
- key 必须拼业务上下文，推荐格式：
"idempotent:{business_type}:{user_id}:{idempotencyKey}"，例如"idempotent:pay:1001:pay_abc123" - 禁止哈希整个请求 body：gzip、空格、字段顺序差异都会让哈希不一致；应提取稳定字段（如
from_account_id、amount、currency、timestamp.Unix()）拼接后哈希 - 必须正则校验 key 格式，例如
^[a-zA-Z0-9_-]{12,64}$，防注入和非法长度 - header 为空时直接拒绝，绝不 fallback 到服务端生成
redis.SetNX 必须带 NX 和 EX，且不能拆成两步
常见翻车点是先 EXISTS 再 SET，或 SetNX 成功后补 EXPIRE。这两者都有竞态窗口或失败残留风险——前者导致并发穿透，后者让 key 永久卡住。
- Go-Redis v9 正确调用：
rdb.SetNX(ctx, key, traceID, 300*time.Second)，它底层自动拼NX EX参数 - TTL 时间必须 ≥ 接口最长耗时 + 安全余量（如支付回调最长 45s，TTL 至少设 60s）
- value 别存空字符串，建议填
traceID或客户端传的idempotencyKey，方便日志对齐 - 调用后必须检查返回的
bool：false 表示 key 已存在，不是错误；err != nil才是连接异常
Redis 故障时不能 fallback 到“放行”，必须返回 503 Service Unavailable
很多人在 rdb.SetNX 报错时 catch 后直接执行业务逻辑，这等于彻底放弃幂等语义——网络抖动、Redis 集群脑裂、配置错误都可能触发，结果就是大量重复写入。
- 只要 Redis 不可用，就必须阻断请求，返回
503，由上游重试或降级策略处理 - 中间件里别用闭包或局部变量存幂等标识，必须通过
context.WithValue(ctx, "idempotent_key", key)透传，handler 中统一从ctx.Value("idempotent_key")取值 - 校验必须放在 HTTP 入口最外层，不能塞进事务中间：否则 DB 写成功但 Redis 失败，下次请求会因 key 缺失被误放行
数据库唯一索引是兜底铁律，不是可选项
所有中间层控制都可能失效：缓存击穿、客户端绕过 header、Redis 故障降级、响应丢包……最终防线永远是 DB 层的联合唯一索引。
- 建索引字段必须含业务语义，例如：
UNIQUE (user_id, idempotency_key)或UNIQUE (order_no, client_order_id) - 插入失败后，精准捕获冲突错误：
pgx.ErrCodeUniqueViolation（PostgreSQL）或mysql.MySQLError.Number == 1062（MySQL） - 不能 catch 所有 error 后静默返回 success；要区分“真失败”（如余额不足）和“已存在”，后者才可返回原始成功响应
- 状态机必须三态（
pending/success/failed），仅靠布尔标记无法应对执行中失败、下游超时等中间态
真正难的不是写对那几行 SetNX，而是把 key 构造、状态流转、错误分支、降级策略全部串成一条无断点的链路——任意一环松动，幂等就形同虚设。线上出问题，90% 不是 Redis 挂了，而是 TTL 设短了、key 拼错了、或者 DB 冲突没识别对。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
