跳到正文
D2-02交易域3 分钟更新于 2026-11

幂等设计

一句话

幂等不是"加个唯一索引",是为每一个可能重复的入口,选一个稳定的幂等键。

本文目录11 节

幂等设计

为什么支付系统的资损,八成从这里开始

一笔钱重复扣、重复发、重复记,几乎都能追溯到同一个动作: 同一个请求到达了两次,而系统执行了两次。

重复的来源比想象中多:

  • 用户双击 / 网络重试
  • 渠道回调重发(渠道的策略通常是「你没回 200 我就一直发」)
  • 我方定时任务重跑
  • 服务崩溃后消息重投
  • 人工在后台点了两下

四类入口,四种幂等键

不存在一个通用的幂等方案。每个入口要用不同的键。

最容易被做错的是第一类

如果服务端自己生成幂等键(比如 uuid()),那幂等就完全失效了—— 因为两次请求会拿到两个不同的键,系统会认为它们是两件事。

规则:幂等键必须由"发起方"提供,且跨重试保持不变。

四个常见错误做法

错误一:用业务字段拼键

md5(订单号 + 金额 + 币种) 看起来聪明,实际上:

  • 用户真的想分两笔付同样金额时,第二笔被当成重复
  • 金额精度一变(分 vs 元),键就变了

错误二:先查后插(check-then-act)

if (!await exists(key)) { await insert(...) } // ❌ 有竞态

两个并发请求会同时通过检查。唯一约束才是唯一可靠的锁。

错误三:幂等表不区分状态

只记「这个键来过」,不记「执行到哪一步」。 结果是:第一次执行到一半崩溃,第二次请求发现键存在 → 直接返回成功, 而业务其实没完成。钱没动,但用户以为成功了。

正确做法是两阶段:

处理中(processing) → 完成(done) / 失败(failed)

请求进来先占位 processing(唯一约束挡住并发) 执行完更新为 done 如果发现键是 processing 且超时,说明上次崩了 → 走查证而不是直接重做

错误四:幂等键没有过期策略 永久保留会撑爆表;无脑设 TTL 又会让「超长重试」变成新请求。 建议:幂等记录保留 ≥ 渠道重试窗口(通常 24~72 小时),且保留的是状态不是结果。

回调幂等的具体写法

-- 占位:靠主键冲突挡住重复 INSERT INTO webhook_events (event_id, channel, status, received_at) VALUES (?, ?, 'processing', ?) ON CONFLICT (event_id) DO NOTHING; -- 影响行数 = 0 说明是重复,直接返回 200

处理成功后 status='done';异常时 status='failed' 并保留原文,供重放。

注意:无论处理成败,对外都要返回 200。 返回 5xx 会让渠道进入重试风暴,而重试解决不了你代码里的 bug—— 它只会把同一批坏数据再推一遍。

幂等 ≠ 去重

这两个词经常混用,但差别很大:

支付系统要的是幂等:即使执行两次,账也只记一次。 靠"去重"是不够的,因为它防不住"同一件事换了张皮"。

自查清单

  • 每个写操作入口都有明确的幂等键,且由发起方提供
  • 幂等表有状态字段(processing / done / failed),不是布尔
  • 并发安全靠唯一约束,不靠先查后插
  • 幂等键的保留期 ≥ 渠道重试窗口
  • 回调无论成败都返回 200
  • 有「键已存在但状态是 processing」的处理路径(走查证,不盲目重做)

依据

  • 分布式系统的 at-least-once 投递语义决定了重复必然发生
  • 卡组织与 PSP 的重试策略普遍是「未确认即重发」
相关阅读