Gin的POST接口重复提交创建多笔订单，根本原因在于业务handler未做幂等校验；Gin本身不自动识别Idempotency-Key或查Redis/数据库去重，需在中间件中标准化提取幂等键、用Redis SetNX实现原子锁，并配合数据库唯一索引作为最终兜底。
为什么 Gin 的 POST 接口重复提交会创建多笔订单
根本不是 Gin 框架的问题，而是业务 handler 里没做任何幂等校验。Gin 的 c.Next() 只负责流转请求，gin.Engine 不会自动识别 Idempotency-Key，也不会查 Redis 或数据库去重。浏览器刷新、Nginx 重试、移动端网络抖动，都会让同一个请求抵达你的 handler 多次——而你写的 createOrder() 函数只要被调用两次，就极可能写入两条记录。
常见错误现象包括：200 OK 返回了，但日志里看到相同 X-Request-ID 出现两次；数据库唯一索引报错 ERROR: duplicate key value violates unique constraint；用户投诉“明明只点了一次，怎么扣了两笔钱”。
如何在 Gin 中间件里安全提取并验证幂等键
别直接信任客户端传的 Idempotency-Key 请求头——它可被伪造、复用或缺失。中间件必须做三件事：标准化键值、校验合法性、绑定到 c 上供后续 handler 使用。
- 用
c.Request.Header.Get("Idempotency-Key")读取，但要检查长度（建议限制 32~64 字符）和字符集（只允许字母、数字、-、_） - 若为空或非法，生成服务端唯一键：
uuid.New().String()，并写回响应头X-Idempotency-Key，方便客户端对齐 - 务必调用
c.Set("idempotent_key", key)，而不是用闭包变量存——Gin 并发请求共享同一中间件实例，闭包变量会互相污染 - 不要在中间件里直接操作业务逻辑（比如查订单状态），只做前置校验和上下文透传
用 Redis SetNX 实现原子性幂等锁的关键细节
最常用也最稳妥的方式是基于请求指纹 + redis.SetNX，但容易踩几个硬坑：
- 指纹不能只拼
Idempotency-Key，得结合业务标识，例如：fmt.Sprintf("idempotent:%d:%s", userID, sha256hex(orderAmount+goodsID+timestamp)) -
SetNX必须带过期时间，如5 * time.Minute，否则 Redis 进程崩溃后锁永远不释放 - 如果业务允许返回历史结果（比如查单、支付查询），得先
GET缓存结果，再SETNX尝试上锁，避免竞态导致重复执行 - Redis 故障时不能 panic，要降级处理：记录告警日志，并放行请求（
return c.Next()），否则整个服务雪崩
示例片段：
key := fmt.Sprintf("idempotent:%d:%s", userID, hashParams(req))
ok, err := rdb.SetNX(ctx, key, "processing", 5*time.Minute).Result()
if err != nil {
log.Warn("redis unavailable, skip idempotent check")
return c.Next()
}
if !ok {
c.AbortWithStatusJSON(409, gin.H{"error": "request already processed"})
return
}为什么不能只靠数据库唯一索引兜底
唯一索引冲突报错是事后补救，不是幂等性保障：
- 错误发生在事务提交阶段，此时可能已完成库存扣减、积分扣除等副作用操作，无法回滚
- HTTP 状态码变成
500或400，前端无法区分是参数错还是重复提交，用户体验断裂 - 高频冲突会打满数据库连接池，拖慢其他正常请求
- 日志里全是
duplicate key错误，掩盖真实并发问题（比如超卖、脏读）
唯一索引只应作为最终防线，和幂等中间件配合使用：中间件拦截 99% 的重复请求，索引兜住那 1% 的极端竞态。
