专栏 · 全栈工程第八篇
幂等:同一操作执行一次和执行 N 次,结果必须一样
一句话:分布式里「重试」是常态(超时重试、MQ at-least-once、用户狂点),没有幂等,每次重试都是一次新写入——幂等就是把「重试安全」变成默认能力。
系列:事务 → 锁 → 幂等 → DDD → 查询优化。数据库事务 · 乐观锁与悲观锁 · 本文 · 领域驱动设计(DDD) · 数据库查询性能优化。
一、什么是幂等
定义:同一业务请求执行一次与执行 N 次,对系统状态的影响相同。
数学表达:f(f(x)) = f(x)。
为什么需要——这些场景都在逼你做幂等:
| 场景 | 来源 |
|---|---|
| 超时重试 | 网络抖了不敢确定成败,只能重试 |
| 用户重复提交 | 前端狂点、弱网重发 |
| 消息重复投递 | MQ 是 at-least-once 语义,一定会有重复 |
| 定时任务重复触发 | 多实例、补偿重跑 |
天然幂等 vs 天然不幂等
| 操作 | 是否幂等 |
|---|---|
SELECT 读 |
✅ |
UPDATE .. SET x = 5(覆盖写/绝对值) |
✅ |
DELETE WHERE id = ? |
✅(删多次结果一样) |
UPDATE .. SET x = x + 1(增量写) |
❌ |
INSERT 无唯一键 |
❌ |
| 转账「扣 100 元」 | ❌ |
优先通过改造写法让操作天然幂等(把
+1换成「按某个唯一维度覆盖/append 去重」),其次才是加幂等机制。
二、核心实现:幂等 key + 幂等表
2.1 幂等 key 谁来生成
| 生成方 | 时机 | 说明 |
|---|---|---|
| 客户端(推荐) | 发起前 | 同一「业务意图」的重试带同一个 key(如 UUID);跨失败重试才能去重 |
| 服务端 | 到达时 | 可控防恶意,但「先落地再重试」流程复杂 |
key 要绑定业务意图:不是「一次 HTTP 请求」一个 key,而是「这次下单/这笔转账」一个 key。
2.2 幂等表结构与处理流
CREATE TABLE idempotent (
idempotent_key VARCHAR(64) PRIMARY KEY, -- 唯一索引是并发兜底
request_hash CHAR(64), -- 防同 key 不同请求
response TEXT, -- 缓存首次响应
status TINYINT, -- 处理中/完成
version BIGINT,
created_at DATETIME
);
收到请求(key)
├─ 已存在 & 同 request_hash → 直接返回缓存响应(重放安全)
├─ 已存在 & 异 request_hash → 409 拒绝(防同 key 被篡改重放)
└─ 不存在 → INSERT 抢占(唯一索引) → 执行业务 → 写 response
↑ 插入冲突 = 别的请求正在处理/已处理 → 走查询返回
唯一索引是最后一道闸:就算代码判断漏了并发窗口,DB 层
Duplicate entry会把第二次插入挡下来——这是任何「先查后插」都替代不了的。
三、常用幂等手段清单
| 手段 | 原理 | 适用 |
|---|---|---|
| 唯一索引/唯一约束 | DB 层拒绝重复插入 | 一切「创建类」操作 |
| 幂等表(见上) | key + 响应缓存 | 通用写操作 |
| Token 防重令牌 | 进入页面先领 token,提交时 SETNX 消费,用过即废 |
表单防重复提交 |
| 乐观锁 version/CAS | WHERE version=? 更新,冲突重试 |
并发更新(见 乐观锁与悲观锁) |
| 状态机 | 终态(SUCCEEDED)拒绝重复执行,只有中间态可重入 | 任务/订单流转 |
| 覆盖写/绝对值 | 写「最终值」而非「增量」 | 能改造的业务写 |
| 分布式锁 | 同时只有一个执行者 | 防并发,不能替代幂等(锁会失效) |
四、幂等 vs 锁 vs 事务(三者关系)
| 解决什么 | 失效时会怎样 | |
|---|---|---|
| 锁(悲观/分布式) | 防「同时写」(并发互斥) | 锁超时/失效 → 可能重复执行 |
| 事务 | 保证「一组写全做或全不做」 | 跨库/外部副作用管不到(见 数据库事务) |
| 幂等 | 防「重复写」(重试安全) | 它就是最后的兜底,不依赖别的 |
一句话:锁挡并发,事务挡半提交,幂等挡重试。三层都要有,幂等是底线。
五、结合 Agent 场景
| 场景 | 幂等落点 |
|---|---|
| 工具调用自动重试 | 工具实现必须幂等:重试一次 = 换个办法再执行,绝不能重复扣款/重复发通知 |
| MQ at-least-once | 消费端按 messageId(或业务单号)做幂等表去重 |
| 定时任务多实例 | 执行端幂等 + 分布式锁双保险(锁失效幂等兜底) |
| Checkpoint | 状态机:completed 步骤拒绝重入,从 nextStepIndex 幂等续跑 |
| 对账 | 长款补单本身也要幂等,防止差错处理变成新差错 |
六、实战案例:现金贷提现双重放款(幂等怎么救)
和 乐观锁与悲观锁 的提现案例 同一个业务、两种故障: 「并发同时」→ 锁去挡;「重复晚到」→ 只能幂等挡。
6.1 场景与没有幂等的惨剧
用户提现 4000,请求网络超时,前端自动重试又把同一个请求发了一遍。
| 时刻 | 请求 1(提现 4000) | 请求 2(超时重试,同一业务意图) |
|---|---|---|
| t1 | 扣款 4000、生成放款单、放款成功 | |
| t2 | 响应在网络里丢了 | |
| t3 | 又扣 4000、又放款一次 | |
| 结果 | 账上只该出 4000,却到账 8000 = 双重放款(资金双出) |
这不是「并发同时改」,而是「同一操作被时间上隔开的两次请求重复执行」。
6.2 为什么锁挡不住、只有幂等能挡
锁防的:两笔【同时在跑】(并发互斥)
幂等防的:请求1 早跑完了,请求2 是【晚到】的重试
→ 此刻没人改,锁全部放行 → 但同一件事被做两遍
晚到的重试,锁看不见;只有幂等(「这笔业务我做过了没?」)能认出来。
6.3 幂等怎么救:幂等表 + 唯一索引
| 请求 | 后端动作 |
|---|---|
| 请求 1 | 查幂等表:无 → 唯一索引抢占插入 → 执行放款 → 结果写回表 |
| 请求 2(重试) | 查幂等表:key 已存在 + 同 hash → 直接返回上次结果,不再执行 |
CREATE TABLE idempotent (
idempotent_key VARCHAR(64) PRIMARY KEY, -- 唯一索引:并发窗口的最后兜底
request_hash CHAR(64), -- 防同 key 被篡改
response TEXT, -- 缓存首次成功结果
status TINYINT, -- 处理中/成功/失败
created_at DATETIME
);
@Transactional
public WithdrawResult withdraw(String requestId, BigDecimal amount) {
// 1) 幂等抢占:requestId 做唯一索引;真重复会抛 Duplicate
boolean first = idempotentMapper.tryInsert(requestId, hash(amount));
if (!first) {
// 这单(或重试)已处理过 → 直接返回缓存结果,绝不再扣一次
return idempotentMapper.getCachedResponse(requestId);
}
try {
WithdrawResult r = withdrawService.process(amount); // 真正放款/扣款
idempotentMapper.markDone(requestId, r);
return r;
} catch (Exception e) {
idempotentMapper.markFailed(requestId); // 标失败,允许重试重入
throw e;
}
}
6.4 它和锁是叠加,不是二选一
- 两笔并发同时到 → 唯一索引的
Duplicate把第二笔拦下(唯一约束 = 「数据库当锁」)。 - 重试晚到 → 靠
tryInsert判「已处理过」,返回缓存结果。 - 理想组合:悲观/乐观锁挡「同时」 + 幂等表挡「晚到」,一次都不要多。
6.5 现金贷幂等落点清单
| 场景 | 幂等 key | 防什么 |
|---|---|---|
| 提现 / 放款请求重试 | requestId = 提现单号 |
双重放款 |
| 还款扣款调用 | repayNo |
重复扣款 |
| MQ 放款/还款回调(at-least-once) | 消费方用 messageId |
Broker 重复投递 |
| 授信申请 | applicationNo |
重复建单 |
金流原则:任何「会动钱/发钱」的异步链路,消息投递都是 at-least-once(至少一次,可能多次)——消费端默认必须幂等,这是底线而非可选项。
七、面试速记
- 定义先行:
f(f(x)) = f(x);重试安全 = 幂等。 - 手段五连:唯一索引 → 幂等表(key+hash+响应缓存) → 状态机 → 乐观锁 CAS → 天然幂等写法。
- 幂等 key 按「业务意图」生成,服务端同 key 异 hash 返回 409。
- 唯一索引是并发窗口的最后兜底,「先查后插」防不住并发。
- 幂等 vs 锁:锁防同时、幂等防重复;锁是优化,幂等是底线。
八、ChangeLog
| 版本 | 日期 | 修改 |
|---|---|---|
| V1 | 2026-10-29 | 初版创建 |
| V1.1 | 2026-11-01 | 新增「六、实战案例:现金贷提现双重放款」,与锁篇提现案例构成「同一场景、两种故障」对照 |
评论