在应对高并发场景时，确保幂等性不能仅依赖“加锁”或“先查再执行”。Go 语言的 goroutine 调度速度快、并发数量大，导致竞态窗口虽然极小但真实存在。必须采用原子操作、状态机、数据库兜底这三层防线，层层咬合，才能扛住峰值压力。
redis.SetNX 是第一道也是最关键的防线
它并非“可选优化”，而是幂等校验的起点。使用 SetNX 时必须同时携带 NX 和 EX 参数，如果拆成两步（Exists + Set），就等于没有做防护。
redis.SetNX(ctx, key, value, ttl)是 Go-Redis v9+ 的标准写法；手写命令时如果顺序错误（比如把EX放在NX前面），会导致语义失效- key 的拼装必须包含完整的上下文：
"idempotent:" + method + ":" + path + ":" + userID + ":" + idempotencyKey，避免不同接口或用户 ID 发生冲突 - ttl 至少要设置为接口最长耗时 + 15 秒的余量（例如超时设 30 秒，这里至少填 45 秒），否则 key 过早过期，重试请求会直接穿透
- value 不要存空字符串，推荐存储
trace_id或客户端时间戳，当出现问题时能快速关联日志 - Redis 连接失败时，必须返回 503 Service Unavailable，绝不能降级为“放行”——幂等语义一旦松动，下游数据库压力会呈指数级上升。这句话，值得反复读三遍。
sync.Map 只适用于单机低流量场景，且必须结构化缓存
不要把它当作 Redis 的替代品。sync.Map 没有过期机制、无法跨进程、不能感知业务生命周期，只适合 QPS 低、服务不重启的场景，而且必须采用结构化缓存。
- 不能只存
bool，必须缓存完整的响应结构体：{status: "success", result: json.RawMessage, timestamp: time.Time}，否则“已存在”时无法安全返回上次结果 - key 的构造要固定，避免使用临时变量或混用字段顺序，否则并发下
Load可能命中错误项 - 必须配置主动清理逻辑：比如每分钟扫描一次
timestamp超过 10 分钟的项，或者当 size > 10000 时删除最老的 10% - 写入前必须先执行
Load，命中就直接返回；没命中才执行业务逻辑，完成后执行Store——遗漏Load步骤相当于裸奔
数据库唯一索引是不可绕过的兜底铁律
所有中间层控制（Redis、内存 Map、甚至 gRPC metadata 拦截）都可能因故障、重启、客户端绕过而失效。数据库层才是最后一道物理防线。
- 索引字段必须覆盖业务语义，例如订单表创建
UNIQUE (user_id, idempotency_key)，而不是仅在idempotency_key单列上建索引 - 插入失败后，必须精准识别唯一冲突：
mysql.MySQLError.Number == 1062或pgx.ErrCodeUniqueViolation，其他错误（如主键冲突、外键失败）属于真实业务异常，需要告警而不是静默处理 - 捕获到唯一约束错误后，不能直接返回成功，必须查询一次数据库确认该记录是否真实存在且状态合法（比如是否被软删除、是否处于 pending 状态）
- 严禁使用“先查再插”做判断——分布式环境下，查和插之间存在天然时间窗口，必然导致脏写
gRPC/HTTP 调用中 context 透传与超时查询必须闭环
网络超时 ≠ 操作失败。上游因 DeadlineExceeded 重发，下游其实已经执行完毕，这是重复请求的核心来源。
- 所有 RPC 调用必须携带
context.WithTimeout，超时后不盲目重试，而是发起幂等查询（查询 Redis 或数据库），确认最终状态 - HTTP 场景使用
X-Request-ID头透传业务 ID，中间件自动注入到context.Value；gRPC 场景在metadata中放入biz_id，服务端拦截器统一提取并绑定 - 重试策略仅针对
Unavailable、DeadlineExceeded等网络类错误，对InvalidArgument、NotFound等业务错误重试毫无意义 - 重试必须带抖动（jitter）和指数退避，例如
BackoffExponential(100*time.Millisecond)+WithMax(3)，避免雪崩
话说回来，真正难的不是写对某一行 SetNX，而是三态状态机（processing/success/failed）在整个调用链路中的一致性对齐——从 HTTP header 到 Redis key，从 context.Value 到 DB 字段，再到异步任务的消费确认，任何一环脱节，幂等性就会塌一角。
