尧图网页设计 
Go 接口幂等性实战从订单支付到分布式系统去重幂等性是高并发服务的安全带。本文从工程角度拆解幂等设计与实现避免你最担心的重复数据。一、什么是幂等多次调用与一次调用的结果一致。支付两次只扣一次下单两次只成功一单。HTTP 语义幂等GET、PUT、DELETE非幂等POST、PATCH二、业务场景用户点多次支付按钮客户端网络重试导致服务器收到多次请求网络超时客户端重发请求MQ 重投造成重复消费这些都需要幂等。三、幂等键Idempotency-KeyPOST /payments Idempotency-Key: 5f7b-2026-07-30-001服务器func(s*PaymentService)Pay(ctx context.Context,req PayReq)error{ifreq.IdempotencyKey{returnerrors.New(missing key)}ifdone,err:s.repo.HasProcessed(req.IdempotencyKey);err!nil{returnerr}elseifdone{returnnil// 已处理}err:s.payCore(ctx,req)iferr!nil{returnerr}returns.repo.MarkProcessed(req.IdempotencyKey)}四、数据库的唯一约束CREATETABLEorders(idVARCHAR(64)PRIMARYKEY,-- 业务 UUIDuser_idBIGINT,amountDECIMAL(10,2),UNIQUEKEYuk_biz(user_id,idempotency_key));插入时如已存在报错捕获错误即视为幂等。五、乐观锁 versiontypeOrderstruct{IDstringStatusstringVersionint}func(o*Order)UpdateStatus(db*sql.DB,statusstring)error{res,err:db.Exec( UPDATE orders SET status ?, version version 1 WHERE id ? AND version ?,status,o.ID,o.Version)ifn,_:res.RowsAffected();n0{returnErrVersionConflict}returnerr}适合修改型操作。六、Redis 幂等集funcTryClaim(ctx context.Context,rdb*redis.Client,keystring,ttl time.Duration)(bool,error){set,err:rdb.SetNX(ctx,key,1,ttl).Result()returnset,err}// callok,_:TryClaim(ctx,rdb,pay:idempotencyKey,5*time.Minute)if!ok{returnnil// 已存在}deferrdb.Del(ctx,key)// 完成且失败则删除否则保留 5min 自动失效Redis 性能高适合短窗口。七、分布式事务的幂等Saga 模式 / TCC 模式都是拆小事务每步骤都需幂等。可以给每条记录打上 idempotency_key保证重复请求仅一次执行。八、踩坑清单幂等键命名空间key 加上 biz 业务前缀避免冲突TTL太短会失效太长会占内存不要用 time.Now() 当 key客户端无法保证幂等幂等 安全 ≠ 容错业务还是要考虑 network retry、circuit break九、实战支付微服务typePaystruct{IdempotencyKeystringOrderIDstringAmountfloat64}func(s*Service)Pay(ctx context.Context,req Pay)error{// 1. 幂等校验ok,_:s.rdb.SetNX(ctx,pay:req.IdempotencyKey,1,10*time.Minute).Result()if!ok{returnErrDuplicate}// 2. 事务扣款err:s.payCore(ctx,req)iferr!nil{s.rdb.Del(ctx,pay:req.IdempotencyKey)// 失败 delete让用户重试returnerr}returnnil}十、总结与展望幂等性的核心是给重复操作加锁。Redis SETNX、数据库 unique key、乐观锁三种武器互补使用。未来随着 ServiceMesh 与 serverless 流行平台层提供 Idempotency-Token 自动注入将成为趋势。十一、参考文献Stripe Idempotent Requests 官方文档阿里云 BAIDU 幂等性文档“Idempotency in distributed transactions” OReilly Go 接口幂等性实战：从订单支付到分布式系统去重
Go 接口幂等性实战从订单支付到分布式系统去重幂等性是高并发服务的安全带。本文从工程角度拆解幂等设计与实现避免你最担心的重复数据。一、什么是幂等多次调用与一次调用的结果一致。支付两次只扣一次下单两次只成功一单。HTTP 语义幂等GET、PUT、DELETE非幂等POST、PATCH二、业务场景用户点多次支付按钮客户端网络重试导致服务器收到多次请求网络超时客户端重发请求MQ 重投造成重复消费这些都需要幂等。三、幂等键Idempotency-KeyPOST /payments Idempotency-Key: 5f7b-2026-07-30-001服务器func(s*PaymentService)Pay(ctx context.Context,req PayReq)error{ifreq.IdempotencyKey{returnerrors.New(missing key)}ifdone,err:s.repo.HasProcessed(req.IdempotencyKey);err!nil{returnerr}elseifdone{returnnil// 已处理}err:s.payCore(ctx,req)iferr!nil{returnerr}returns.repo.MarkProcessed(req.IdempotencyKey)}四、数据库的唯一约束CREATETABLEorders(idVARCHAR(64)PRIMARYKEY,-- 业务 UUIDuser_idBIGINT,amountDECIMAL(10,2),UNIQUEKEYuk_biz(user_id,idempotency_key));插入时如已存在报错捕获错误即视为幂等。五、乐观锁 versiontypeOrderstruct{IDstringStatusstringVersionint}func(o*Order)UpdateStatus(db*sql.DB,statusstring)error{res,err:db.Exec( UPDATE orders SET status ?, version version 1 WHERE id ? AND version ?,status,o.ID,o.Version)ifn,_:res.RowsAffected();n0{returnErrVersionConflict}returnerr}适合修改型操作。六、Redis 幂等集funcTryClaim(ctx context.Context,rdb*redis.Client,keystring,ttl time.Duration)(bool,error){set,err:rdb.SetNX(ctx,key,1,ttl).Result()returnset,err}// callok,_:TryClaim(ctx,rdb,pay:idempotencyKey,5*time.Minute)if!ok{returnnil// 已存在}deferrdb.Del(ctx,key)// 完成且失败则删除否则保留 5min 自动失效Redis 性能高适合短窗口。七、分布式事务的幂等Saga 模式 / TCC 模式都是拆小事务每步骤都需幂等。可以给每条记录打上 idempotency_key保证重复请求仅一次执行。八、踩坑清单幂等键命名空间key 加上 biz 业务前缀避免冲突TTL太短会失效太长会占内存不要用 time.Now() 当 key客户端无法保证幂等幂等 安全 ≠ 容错业务还是要考虑 network retry、circuit break九、实战支付微服务typePaystruct{IdempotencyKeystringOrderIDstringAmountfloat64}func(s*Service)Pay(ctx context.Context,req Pay)error{// 1. 幂等校验ok,_:s.rdb.SetNX(ctx,pay:req.IdempotencyKey,1,10*time.Minute).Result()if!ok{returnErrDuplicate}// 2. 事务扣款err:s.payCore(ctx,req)iferr!nil{s.rdb.Del(ctx,pay:req.IdempotencyKey)// 失败 delete让用户重试returnerr}returnnil}十、总结与展望幂等性的核心是给重复操作加锁。Redis SETNX、数据库 unique key、乐观锁三种武器互补使用。未来随着 ServiceMesh 与 serverless 流行平台层提供 Idempotency-Token 自动注入将成为趋势。十一、参考文献Stripe Idempotent Requests 官方文档阿里云 BAIDU 幂等性文档“Idempotency in distributed transactions” OReilly