幂等校验必须在入口处原子完成，应使用Redis的SET key value EX ttl NX命令或Go-Redis v9的rdb.Set(ctx, key, value, ttl)配SetArgs{NX: true}实现；key需拼接业务上下文，value建议用X-Request-ID；Redis故障时须返回503而非降级放行；状态机需支持processing/succeeded/failed三态并结构化缓存响应；客户端Idempotency-Key须正则校验，且通过context透传而非闭包变量；DB唯一索引为最终兜底，字段须覆盖业务语义。
幂等校验必须在入口处原子完成，不能拆成两步
很多同学用 redis.Exists() 判断 key 是否存在，再用 redis.Set() 写入，这会引发竞态：中间若服务崩溃或 Redis 连接中断，key 就永远没过期，后续所有请求都被拦截。真正的原子操作是 SET key value EX 3600 NX —— NX 表示“仅当不存在时设置”，EX 表示自动过期，整个命令不可分割。
Go-Redis v9 推荐直接调 rdb.Set(ctx, key, value, ttl) 并传 redis.SetArgs{NX: true}，它底层自动拼装原子命令；别手写字符串发 SET，参数顺序错一个（比如 EX 和 NX 位置颠倒）就会失效。
- 过期时间必须大于业务最长耗时 + 网络抖动余量（例如支付接口超时设 30s，ttl 至少 45s）
- value 别存空字符串，建议填
X-Request-ID或客户端传的X-Idempotency-Key，方便日志对齐 - key 必须拼业务上下文，例如
"idempotent:pay:" + userID + ":" + idempotencyKey，裸用 header 值会导致不同用户/订单互相污染
Redis 故障时不能 fallback 到“放行”，得返回 503
网络异常不只是客户端重试的原因，也可能是服务端依赖的 Redis 暂时不可用。此时若降级为“跳过校验直接执行”，等于放弃幂等语义——重复请求照样写多条数据。正确做法是快速失败：if errors.Is(err, redis.Nil) || errors.Is(err, context.DeadlineExceeded) { http.Error(w, "service unavailable", http.StatusServiceUnavailable); return }。
这个 503 不是甩锅，而是明确告诉上游：“这次我无法保证幂等，请按你自己的策略决定是否重试”。前端或网关收到 503 后，可结合自身重试逻辑（如指数退避）再发一次，而不是无脑刷屏。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 别用
sync.Map临时兜底——它不跨进程、无自动过期、并发下易污染，只适合单机低 QPS 场景且必须配定时清理 - DB 唯一索引是最终防线，但不是校验环节：它只兜底 Redis 失效、缓存击穿、客户端绕过 header 等场景
- 唯一索引字段要覆盖业务语义，例如
UNIQUE (user_id, idempotency_key)，别只建在单列上
状态机必须覆盖三态，且结果缓存要结构化
只存 "processing" 或 "succeeded" 是不够的。真实场景中，请求可能卡在中间状态（如 DB 写成功但响应丢失），也可能失败后需要人工干预。所以至少要支持 processing / succeeded / failed 三种状态，并允许客户端根据状态做不同动作。
缓存响应体时，别只存 bool 或 string。推荐用结构体：type IdempotentResult struct { Status string `json:"status"` Body []byte `json:"body"` StatusCode int `json:"status_code"` Timestamp time.Time `json:"timestamp"` }。这样命中 succeeded 时能原样返回上次的 HTTP Status 和 body，包括自定义 header（如 X-Idempotent-Response: true）。
- 状态更新要用 Lua 脚本或 Redis 事务保证原子性，防止“查-判-写”中间被覆盖
- failed 状态不要永久保留，应设较短 TTL（如 1 小时），避免堆积无效 key
- 客户端生成的
X-Idempotency-Key必须正则校验格式（如^[a-zA-Z0-9_-]{12,64}$），防 Redis key 注入
context 透传幂等标识，别用闭包变量存
Gin/Echo 中间件里用局部变量或闭包存 idempotent_key 是高危操作——并发请求会互相覆盖，一个请求的 key 被另一个覆盖，导致误拒或漏判。必须通过 context.WithValue() 注入，并在 handler 里用 c.Request.Context().Value() 取出。
更稳妥的是把幂等键绑定到 trace ID 上：从 c.GetHeader("X-Request-ID") 或 c.GetHeader("X-Idempotency-Key") 取值后，立即存入 context，后续所有日志、DB 查询、RPC 调用都带上它。这样即使中间经过多个中间件或 goroutine，也能保持上下文一致。
- 取不到
X-Idempotency-Key应直接拒绝（http.StatusPreconditionFailed），不默认生成 UUID - 别哈希整个请求 body——gzip、空格、字段顺序都会导致哈希不一致；客户端可控的稳定标识才是可靠指纹
- gRPC 场景下，应在
metadata.MD里塞biz_id，服务端拦截器统一提取并绑定到 context
SetNX，而是让状态机生命周期和业务执行边界对齐：Redis 里写 processing 的那一刻，必须是业务逻辑开始前的最后一个原子点；DB 插入成功的那一刻，必须同步更新 Redis 状态为 succeeded；任何一环断开，都要有明确的 fallback 路径和可观测痕迹。 
