go接口幂等需分三层：redis.setnx原子拦截（带ex、不拆步）、结构化缓存结果（含status/result/timestamp）、数据库唯一索引兜底；缺一不可。
Go 语言接口幂等不能靠“加个中间件”或“设个 Redis key”就认为万事大吉。真正能落地的方案，必须分层：用 redis.SetNX 快速拦截重复请求，用结构化缓存值保存结果，再靠数据库唯一索引兜底防漏——三层缺一不可。
为什么 redis.SetNX 必须带 EX 且不能拆成两步
常见错误是先 EXISTS 再 SET，或者 SETNX 成功后补 EXPIRE。前者有竞态窗口，两个 goroutine 同时查到 key 不存在，都会写入；后者若 EXPIRE 失败（比如 Redis 连接中断），key 就永久卡住，后续所有重试全被误拒。
-
SetNX(ctx, key, value, ttl)是原子命令，v9 客户端已封装好，直接用，别手拼 - TTL 时间必须 ≥ 接口最长耗时 + 网络抖动余量（例如支付回调超时 45s，TTL 至少设 60s）
- value 别用空字符串，建议填
trace_id或客户端传的idempotency_key，方便日志对齐 - 如果
SetNX返回false，说明 key 已存在，直接返回409 Conflict，不要继续执行业务逻辑
sync.Map 在什么场景下可用、又容易在哪翻车
sync.Map 只适合单机、QPS 几百以内的轻量服务，比如内部工具接口或小流量后台。它比 Redis 快、零依赖，但不是分布式方案的平替。
- key 必须带上下文，推荐格式：
"idempotent:" + method + ":" + path + ":" + clientID + ":" + idempotencyKey，避免退款和下单 key 冲突 - value 不能是
bool，得是结构体：{status: "success", result: json.RawMessage, timestamp: time.Time}，否则命中缓存时没法原样返回响应 - 写入前必须先
Load，命中就直接返回；没命中才执行业务逻辑，完成后必须Store，不能只靠 if 判断 - 没有自动过期，得自己配定时清理：比如每分钟扫一次
timestamp超过 10 分钟的项，或 map size > 10000 就删最老的 10%
数据库唯一索引为什么是“兜底铁律”，而不是可选项
所有中间层控制都可能失效：Redis 故障降级、缓存击穿、客户端绕过 header、网络重传、甚至 Lua 脚本执行一半 panic——这时 DB 层才是最后一道不可绕过的防线。
- 订单表必须建联合唯一索引：
UNIQUE (user_id, idempotency_key)，不是为了“防重复”，而是让重复插入直接报错 - Go 中识别冲突要精准：
pgx.ErrCodeUniqueViolation（PostgreSQL）或mysql.MySQLError.Number == 1062（MySQL），别catch所有 error 后静默返回 success - 插入失败后，别直接抛错，应先查 DB 确认是否真已存在；若存在，返回上次成功结果（需从缓存或 DB 读取）
- 索引字段别选太宽（比如整个 request body 哈希），用客户端生成的短 key 最稳妥，写性能也更好
幂等标识怎么透传才不被污染
在 Gin/Echo 或原生 net/http 中，千万别用闭包或局部变量存 idempotency_key —— 并发请求会互相覆盖。
- 从
c.Request.Header.Get("X-Idempotency-Key")取值，为空应拒绝，不默认生成 - 校验前先正则过滤格式，比如
^[a-zA-Z0-9_-]{12,64}$，防 Redis key 注入 - 取出后塞进
context.Context，用ctx.WithValue透传，handler 里通过ctx.Value("idempotent_key")拿 - RPC 场景下，
IdempotencyKey应作为Request结构体字段，而非仅放 header，避免 gRPC metadata 丢失或代理截断
最常被忽略的是「缓存结果的完整性」：很多实现只记“是否执行过”，却不存状态码、响应体、时间戳。一旦响应丢失重试，用户拿到 409 却不知道上次到底成功没——这已经不是幂等，是体验灾难。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
