幂等设计:唯一键、Token、状态机与去重表的四条路径

幂等设计:唯一键、Token、状态机与去重表的四条路径

Hello,我是小兔大白糖。 网络超时后客户端一重试,订单多了一笔、余额多冻了一份——排障到最后,多半不是「再加一把锁」,而是同一意图执行 N 次,副作用还在放大。写成这篇,给熟悉超时重试、MQ 至少一次投递,却还把「前端防抖」当幂等的后端同学:做一次业界向的幂等心智模型与选型调研。

说明:伪流程、表结构与数字均为教学脱敏 / 示意,不绑定某司业务栈。文中「四条路径」是常见做法归纳;公开 API 只引用可核对文档(如 Stripe Idempotency-Key),不声称某厂官方内幕。

估计阅读时间:12 分钟


目录


为什么现在要关心

硬规则一:在重试与至少一次投递下,幂等是保险,不是可选项。

单体里「成或败」常能当场看见;分布式里常见的是不可知窗口——请求发出去了,响应丢了,你不知道对面有没有写成功。可靠系统必须重试;重试若不幂等,副作用会按次数放大。

你看到的现象常见真相
用户双击提交,两笔订单入口无 Token / 无业务单号唯一约束
超时重试后余额多冻一份冻结是累加语义,没有 CAS 状态或唯一冻结单号
MQ Rebalance 后重复消费,副作用翻倍消费侧只靠内存标志,无去重表 / 业务 UK
「加了分布式锁还是重复执行」锁只买互斥,不买「同一意图只生效一次」
Token 过期后又当成新请求跑一遍幂等键 TTL 与业务主键关系没写进合同

本系列前面几篇谈过事务、锁、限流熔断:它们都会把「失败后重试」推向入口。重试合同成立的前提,是副作用合同也成立。

超时重试时客户端不知道服务端是否已成功;无幂等则重试放大副作用
超时重试时客户端不知道服务端是否已成功;无幂等则重试放大副作用 · 点击查看 SVG 原图

心智模型:电梯按钮与演唱会门票

主比喻:幂等像电梯按钮——按 1 次与按 100 次,系统状态应一致;Token 像演唱会门票——核销后同一张票再扫,结果仍是「已入场」。

  • 电梯按钮:重复动作不放大副作用(人话版的 f(f(x)) = f(x))。
  • 自动售货机投币:卡住后「退币再投」若内部已计数,可能出两罐——典型非幂等。
  • 演唱会门票(Token):先发唯一凭证,提交时原子核销;截图发给十个人,也只有第一次成功。
比喻角色工程对应人话
电梯按钮赋值 / 删除 / 合法状态跃迁重复做,终态一样
售货机投币累加、无 UK 的插入重复做,副作用累加
门票核销Token / Idempotency-Key 消费入口先挡住重复点

类比局限一句说清:电梯与门票解释「重复不放大副作用」;解释不了幂等键由谁生成、TTL 多长、与业务主键是否同一把钥匙——那是作用域合同。


精确定义:幂等判定与作用域

幂等(Idempotency)= 同一操作意图执行一次与执行任意多次,对系统状态的影响相同。

HTTP 方法的幂等是语义约定(GET/PUT/DELETE 常标为幂等,POST 常否);真正落地靠业务层 + 数据层联合保证。判定看它对系统状态做什么,不看「调了几次接口」。

操作形态是否天然偏幂等示例(教学)
查询是GET /orders/123
赋值 / 覆盖写是SET status = PAID
按主键删除是删已不存在的行,终态仍是「没有」
累加 / 无 UK 插入否balance = balance + 100;裸 INSERT
复合流程常否查库存 → 扣减 → 建单,重试可能超卖

硬规则三(提前钉死):幂等键作用域必须写清——谁生成、TTL、与业务主键关系。

合同项要写清的问题常见答案(示意)
生成方客户端还是服务端预发?下单号客户端生成;Token 服务端预发
稳定重试同一次意图重试是否携带同一键?必须同一;否则防不住超时重试
TTL / 保留期键多久失效?响应快照留多久?Token 分钟级;Key 缓存按公开 API 常见 24h 量级(示意)
与业务主键是同一把钥匙,还是入口票 + 业务单号两层?常叠加:Token 拦入口,order_no 兜数据

服务端从参数「猜」指纹(如哈希到分钟)永远有误判;尽量让发起方声明「这是不是同一次意图」。


四条路径怎么选

硬规则二:四条常见路径——唯一键、Token、状态机、去重表——可叠加,不是互斥银弹。

四条幂等路径:唯一键、Token、状态机、去重表,可按入口到消息层叠加
四条幂等路径:唯一键、Token、状态机、去重表,可按入口到消息层叠加 · 点击查看 SVG 原图
路径做法(人话)适合代价 / 边界
唯一键(UK)业务表对业务单号建唯一索引;冲突当「已处理」查回有明确业务主键的写入键必须由请求方带来;冲突观测与返回策略要设计
Token先发短时凭证,提交时原子消费(删 / CAS / Lua)用户触发的提交、防双击要 TTL;业务失败后如何重试要另有下层兜底
状态机只允许合法跃迁:WHERE status = 期望 的 CAS 更新长流程(创建 → 处理 → 终态)CAS 失败要区分「已是目标态」与「并发撞车」
去重表独立记录已处理键;可带响应快照MQ 消费、第三方回调、定时任务实例要清理 / 归档;别无限涨表

唯一键:数据层兜底

教学示意(非某库契约):

-- 教学示意:业务单号唯一
UNIQUE KEY uk_order_no (order_no)

要点:

  1. 键由业务方在请求里带上(UUID / 雪花等),重试不变。
  2. 唯一冲突 ≠ 业务错误——常应返回上次结果,而不是 500。
  3. 自增主键不能当幂等键——服务端生成的 ID,客户端重试带不回同一把钥匙。

Token:入口拦重复点

常见消费模式(教学):

模式思路代价
原子获取并删除一次成功消费依赖支持该原子命令的缓存版本
CAS / 事务兼容旧缓存开销更大
脚本原子自定义 get+del要维护脚本

门票核销后,若业务执行失败,客户端再来时 Token 可能已没——下层唯一键或去重表要能回答「上次到底成没成」。 只删 Token、不记结果,是常见半成品。

状态机:流程天然防重

-- 教学示意:只有 PROCESSING 才能落到 FROZEN
UPDATE biz_order
SET status = 'FROZEN'
WHERE order_no = ?
  AND status = 'PROCESSING';
  • 更新行数 1:本次跃迁成功。
  • 行数 0 且当前已是 FROZEN:幂等返回。
  • 行数 0 且是别的态:可能是并发冲突——别一刀切当成重复请求。

去重表:消息与回调

适用:消费 msgId、支付/身份类回调、定时任务实例 ID。比业务表 UK 多两样能力:跨多表统一记账、可选保存响应快照(重复请求直接回放上次响应)。

公开支付 API 的常见叙事(可核对文档,非内幕):客户端带稳定 Key → 服务端首次执行并缓存响应 → 同 Key 同参直接回放。这正是「去重表 + 快照」在 HTTP 层的形态。


公开参照与教学场景

公开可核对参照:Stripe 要求变更类请求携带 Idempotency-Key;同 Key 复用首次响应;同 Key 不同参数则拒绝。 启示不是「抄一家」,而是合同写清了三件事——键、保留期、参数绑定。

教学场景矩阵(脱敏示意,可按你们域改名):

场景常见叠加说明
用户提交创建Token + 业务 UK防双击 + 防超时重放
资金类状态推进状态机 + UKCAS 跃迁;单号兜底
MQ 消费去重表(± 业务 UK)至少一次投递的标配叙事
第三方回调去重表 + 响应快照对方会重推;要能回放
定时补偿任务实例键 + 状态机断点续传靠子步骤幂等

分层不是「入口做了后面就免做」:网关 Token 挡不住服务间 RPC 重试;消费去重挡不住同域补偿任务。每层买不同风险,数据库唯一索引常是最后兜底。

断点续传人话:把大操作拆成各自幂等的子步骤,每步落持久化状态;挂了再来时按状态跳到未完成步,而不是整单重放非幂等累加。

少量表述级代码(教学,合计控制行数):

consume(token) -> first?
  yes -> insert order_no (UK) -> CAS status
  no  -> load by order_no / return cached response

常见坑

  1. 只靠前端防抖
    双击只是一种重复;超时重试、MQ 重投、补偿任务都绕过 UI。

  2. 以为分布式锁 = 幂等
    锁买互斥;锁超时释放后重试,仍可能再跑一遍。锁与幂等互补,不互相替代。(见本系列锁篇心智模型。)

  3. 用库自增 ID 当幂等键
    客户端重试带不回同一 ID;意图对不齐。

  4. Token 删了就不记结果
    业务失败后无法安全回答「要不要再执行」;要下层 UK / 快照。

  5. 去重表永不清理、无冲突观测
    表无限涨;重复命中率、冲突原因看不见,线上只能靠猜。

  6. 消息幂等只靠缓存 SETNX
    过期与主从切换会丢键;金融级叙事通常要持久化唯一约束兜底。

  7. CAS 失败一律当幂等成功
    可能是并发撞到中间态;要查当前状态再分支。

  8. 忽略「第一次失败、第二次条件已变」
    幂等强调结果与意图一致,不等于「永远只跑一次」;要区分可重试失败与终态失败。


选型结论

  1. 先承认不可知窗口:超时与至少一次投递下,无幂等就等于同意副作用按次放大。
  2. 四条路径按风险叠加:入口 Token、数据 UK、流程状态机、消息/回调去重表——按场景裁剪,不迷信单层。
  3. 幂等键合同写清三件事:谁生成、TTL/保留期、与业务主键关系;同意图重试必须同键。
  4. 冲突要当「已处理」设计:查回或回放快照,而不是把唯一冲突打成 500。
  5. 用失败形态验收:双击、超时重试、Rebalance 重投、补偿任务——说不清哪一种被哪一层接住,就还没设计完。

下一步:列一张「写路径副作用表」——每条路径标生成方键、TTL、落哪张 UK/去重表、状态机合法边;压测时专门打「成功但丢响应」与「重复投递」两条用例。

系列导航(distributed-deep;前序未上线前先占位,发布时再互链):