
Hello,我是小兔大白糖。 网络超时后客户端一重试,订单多了一笔、余额多冻了一份——排障到最后,多半不是「再加一把锁」,而是同一意图执行 N 次,副作用还在放大。写成这篇,给熟悉超时重试、MQ 至少一次投递,却还把「前端防抖」当幂等的后端同学:做一次业界向的幂等心智模型与选型调研。
说明:伪流程、表结构与数字均为教学脱敏 / 示意,不绑定某司业务栈。文中「四条路径」是常见做法归纳;公开 API 只引用可核对文档(如 Stripe
Idempotency-Key),不声称某厂官方内幕。
估计阅读时间:12 分钟
目录
为什么现在要关心
硬规则一:在重试与至少一次投递下,幂等是保险,不是可选项。
单体里「成或败」常能当场看见;分布式里常见的是不可知窗口——请求发出去了,响应丢了,你不知道对面有没有写成功。可靠系统必须重试;重试若不幂等,副作用会按次数放大。
| 你看到的现象 | 常见真相 |
|---|---|
| 用户双击提交,两笔订单 | 入口无 Token / 无业务单号唯一约束 |
| 超时重试后余额多冻一份 | 冻结是累加语义,没有 CAS 状态或唯一冻结单号 |
| MQ Rebalance 后重复消费,副作用翻倍 | 消费侧只靠内存标志,无去重表 / 业务 UK |
| 「加了分布式锁还是重复执行」 | 锁只买互斥,不买「同一意图只生效一次」 |
| Token 过期后又当成新请求跑一遍 | 幂等键 TTL 与业务主键关系没写进合同 |
本系列前面几篇谈过事务、锁、限流熔断:它们都会把「失败后重试」推向入口。重试合同成立的前提,是副作用合同也成立。
心智模型:电梯按钮与演唱会门票
主比喻:幂等像电梯按钮——按 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、状态机、去重表——可叠加,不是互斥银弹。
| 路径 | 做法(人话) | 适合 | 代价 / 边界 |
|---|---|---|---|
| 唯一键(UK) | 业务表对业务单号建唯一索引;冲突当「已处理」查回 | 有明确业务主键的写入 | 键必须由请求方带来;冲突观测与返回策略要设计 |
| Token | 先发短时凭证,提交时原子消费(删 / CAS / Lua) | 用户触发的提交、防双击 | 要 TTL;业务失败后如何重试要另有下层兜底 |
| 状态机 | 只允许合法跃迁:WHERE status = 期望 的 CAS 更新 | 长流程(创建 → 处理 → 终态) | CAS 失败要区分「已是目标态」与「并发撞车」 |
| 去重表 | 独立记录已处理键;可带响应快照 | MQ 消费、第三方回调、定时任务实例 | 要清理 / 归档;别无限涨表 |
唯一键:数据层兜底
教学示意(非某库契约):
-- 教学示意:业务单号唯一
UNIQUE KEY uk_order_no (order_no)要点:
- 键由业务方在请求里带上(UUID / 雪花等),重试不变。
- 唯一冲突 ≠ 业务错误——常应返回上次结果,而不是 500。
- 自增主键不能当幂等键——服务端生成的 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 | 防双击 + 防超时重放 |
| 资金类状态推进 | 状态机 + UK | CAS 跃迁;单号兜底 |
| MQ 消费 | 去重表(± 业务 UK) | 至少一次投递的标配叙事 |
| 第三方回调 | 去重表 + 响应快照 | 对方会重推;要能回放 |
| 定时补偿 | 任务实例键 + 状态机 | 断点续传靠子步骤幂等 |
分层不是「入口做了后面就免做」:网关 Token 挡不住服务间 RPC 重试;消费去重挡不住同域补偿任务。每层买不同风险,数据库唯一索引常是最后兜底。
断点续传人话:把大操作拆成各自幂等的子步骤,每步落持久化状态;挂了再来时按状态跳到未完成步,而不是整单重放非幂等累加。
少量表述级代码(教学,合计控制行数):
consume(token) -> first?
yes -> insert order_no (UK) -> CAS status
no -> load by order_no / return cached response常见坑
-
只靠前端防抖
双击只是一种重复;超时重试、MQ 重投、补偿任务都绕过 UI。 -
以为分布式锁 = 幂等
锁买互斥;锁超时释放后重试,仍可能再跑一遍。锁与幂等互补,不互相替代。(见本系列锁篇心智模型。) -
用库自增 ID 当幂等键
客户端重试带不回同一 ID;意图对不齐。 -
Token 删了就不记结果
业务失败后无法安全回答「要不要再执行」;要下层 UK / 快照。 -
去重表永不清理、无冲突观测
表无限涨;重复命中率、冲突原因看不见,线上只能靠猜。 -
消息幂等只靠缓存 SETNX
过期与主从切换会丢键;金融级叙事通常要持久化唯一约束兜底。 -
CAS 失败一律当幂等成功
可能是并发撞到中间态;要查当前状态再分支。 -
忽略「第一次失败、第二次条件已变」
幂等强调结果与意图一致,不等于「永远只跑一次」;要区分可重试失败与终态失败。
选型结论
- 先承认不可知窗口:超时与至少一次投递下,无幂等就等于同意副作用按次放大。
- 四条路径按风险叠加:入口 Token、数据 UK、流程状态机、消息/回调去重表——按场景裁剪,不迷信单层。
- 幂等键合同写清三件事:谁生成、TTL/保留期、与业务主键关系;同意图重试必须同键。
- 冲突要当「已处理」设计:查回或回放快照,而不是把唯一冲突打成 500。
- 用失败形态验收:双击、超时重试、Rebalance 重投、补偿任务——说不清哪一种被哪一层接住,就还没设计完。
下一步:列一张「写路径副作用表」——每条路径标生成方键、TTL、落哪张 UK/去重表、状态机合法边;压测时专门打「成功但丢响应」与「重复投递」两条用例。
系列导航(distributed-deep;前序未上线前先占位,发布时再互链):
- seriesOrder 1:/blog/distributed_tx_saga_tcc/ — 分布式事务 Saga / TCC
- seriesOrder 2:/blog/distributed_lock_selection/ — 分布式锁选型
- seriesOrder 3:/blog/cap_base_consistent_hash/ — CAP / BASE 与一致性哈希
- seriesOrder 4:限流与熔断(本系列定稿 slug 时请避开站内已有
perf-reliability同名文) - 本篇(seriesOrder 5):幂等四条路径与作用域合同
- seriesOrder 6:/blog/service_discovery_registry/ — 注册发现(发布后补链)