接口幂等性必须在网关或服务入口层统一拦截，不可依赖业务代码；POST因HTTP重试机制和非幂等语义最易出问题；推荐Redis SetNX+过期时间实现令牌校验，并以数据库唯一索引为最终防线。
接口幂等性不能靠业务代码硬扛，必须在网关或服务入口层做统一拦截——否则每个 handler 都要重复写校验逻辑，漏一个就全盘失效。
为什么 POST 接口最容易出幂等问题
HTTP 协议本身不保证重试语义，客户端（尤其是移动端）在网络抖动时会自行重发请求；而 POST 默认是非幂等的，比如创建订单、扣减库存、发起支付。一旦后端没做防护，重复请求就会导致数据异常（如单子建了两次、余额多扣一次）。
常见错误现象：duplicate key violation、insufficient balance、日志里看到相同 trace_id 或 request_id 出现多次但状态不一致。
- 不要依赖前端加防重按钮或禁用提交按钮——这层控制极易绕过
- 不要只在校验阶段查一遍数据库就放行，得确保“检查 + 执行”是原子操作
- 避免用时间戳或随机数做唯一标识：客户端生成不可信，服务端需主导 ID 生成
用 redis.SetNX + 过期时间实现轻量级幂等令牌
这是 Golang 微服务中最常用、最易落地的方案：客户端每次请求带一个业务侧生成的 idempotency_key（比如 user_id:order_create:20250520:abc123），服务端用它作为 Redis key 尝试设值，成功才继续执行业务逻辑。
关键点在于：SetNX 必须带过期时间（如 30 * time.Second），否则服务异常崩溃后 key 永久残留，后续合法请求会被误拒。
- 推荐使用
github.com/go-redis/redis/v9的SetNX(ctx, key, value, ttl)方法 -
value建议填入当前请求的trace_id或request_id，便于排查冲突来源 - 若
SetNX返回false，直接返回409 Conflict并附带提示："request already processed" - 注意 Redis 连接池配置，避免因超时或失败导致幂等逻辑被跳过
数据库唯一索引才是最终防线
Redis 只能降低并发冲突概率，不能 100% 保证。比如两个请求几乎同时通过 SetNX（极小窗口），或 Redis 故障降级，这时就得靠数据库兜底。
例如订单表加联合唯一索引：UNIQUE INDEX idx_user_id_order_no (user_id, order_no)，其中 order_no 是服务端生成的全局唯一号（非自增 ID）。
- 别用 UUID 或雪花 ID 直接当幂等键——它们不携带业务上下文，无法区分“同一用户重复下单”和“不同用户正常下单”
- 插入失败捕获
ErrDuplicateEntry（MySQL）或unique_violation（PostgreSQL），然后查库确认是否真已存在该记录 - 查到已有记录后，应原样返回原始响应（含原始订单号、时间等），而不是返回新生成的数据
gRPC 场景下怎么透传幂等标识
HTTP 接口可以靠 header（如 X-Idempotency-Key）传递，但 gRPC 没有标准 header 约定，容易遗漏。必须在 proto 定义中显式加入字段：
message CreateOrderRequest {
string idempotency_key = 1; // 强制要求客户端填写
string user_id = 2;
int64 amount = 3;
}服务端 middleware 中统一提取并校验，不满足则直接返回 status.Error(codes.InvalidArgument, "idempotency_key required")。
- 禁止在 handler 里做
if req.IdempotencyKey == ""判断——这会让校验逻辑散落各处 - 如果用 kratos、go-zero 等框架，优先走 interceptor / middleware 注册机制，而非每个 service 方法手动写
- 注意 gRPC gateway 转 HTTP 时，要配置好 header 映射，否则外部调用走 HTTP 入口会丢失幂等键
真正难的不是某一种方案的实现，而是把幂等逻辑下沉到框架层、和 tracing / logging / metrics 对齐，并让所有新接口默认继承这套约束——否则靠人肉 review，迟早漏掉一个 POST /v1/refund。
