幂等:同一操作执行一次和执行 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 新增「六、实战案例:现金贷提现双重放款」,与锁篇提现案例构成「同一场景、两种故障」对照

评论

加载中…
评论通过 GitHub 安全存储,提交后稍等片刻显示。