幂等(idempotent / idempotence) 说的是:同一个操作执行一次和执行多次,对系统最终状态造成的影响是一样的。 换言之,「重发一次」不会带来「多做一次」的后果——在网络会超时、消息会重投、用户会连点两次的世界里,这是几乎一切可靠系统的第一道纪律。
先记住判断口径:看状态,不看响应。 一个操作是否幂等,只取决于它把服务端数据改成了什么,与它返回 200 还是 409、返回一个对象还是两个对象都无关。
这个词来自数学:满足 f(f(x)) = f(x) 的函数就是幂等函数,例如绝对值 |x|、min(x, 0)——连做两次和做一次没有区别。
搬到工程里,语义被弱化了,但骨架没变:「重复施加」不等于「效果累加」。
// 非幂等:每调用一次,余额就多 100 function addBalance(balance) { return balance + 100; } // 幂等:无论调用多少次,结果都停在这个值上 function setBalance() { return 500; }
分水岭在于这个操作是「写入一个确定的结果」还是「基于当前值做增量」。前者天然幂等,后者必须靠额外手段才能幂等。
因为现实里有三件事无法避免:
一个值得背下来的等式:
**at-least-once 投递 + 消费端幂等 = 事实上的恰好一次(effectively-once)**
与其追求代价高昂的「精确一次投递」,业界更常见的做法是把重复挡在业务侧。
HTTP 规范(RFC 9110)规定了各方法的幂等性,这是所有 API 设计的公共约定:
| 方法 | 安全(不改状态) | 幂等 | 说明 |
|---|---|---|---|
GET / HEAD | 是 | 是 | 只读;可被爬虫、预取、浏览器回退任意重放 |
OPTIONS | 是 | 是 | 探测能力 |
PUT | 否 | 是 | 用请求体整体替换目标资源:同样的 PUT 发 N 次,资源都是那个样子 |
DELETE | 否 | 是 | 删掉就不存在了:第一次 200/204,第二次通常 404,但服务端状态相同 |
POST | 否 | 否 | 语义是「提交 / 创建」,发 N 次就可能创建 N 条记录 |
PATCH | 否 | 通常否 | 看补丁内容:{“name”:“张三”} 幂等,{“balance”:{“+”:100}} 不幂等 |
两条容易考的推论:
方法层面的细节可对照 get_put_post。另外注意:规范认为 DELETE 幂等,前提是接口老老实实删除「这个 URL 指向的那个资源」;如果有人把接口写成「删除最新一条记录」,那它就已经破坏幂等性了——这是接口的锅,不是定义的锅。
唯一索引是把「幂等」写进数据模型的最简单办法:重复插入直接违反约束,什么都不会发生。
-- 幂等插入:order_no 重复时直接跳过 INSERT INTO `order` (order_no, amount) VALUES ('NO202405010001', 9900) ON CONFLICT (order_no) DO NOTHING; -- PostgreSQL / SQLite -- MySQL 写法 INSERT INTO `order` (order_no, amount) VALUES ('NO202405010001', 9900) ON DUPLICATE KEY UPDATE order_no = order_no; -- 冲突时什么都不改
-- 非幂等:重试一次就多扣一次 UPDATE account SET balance = balance - 100 WHERE id = 1; -- 幂等:写入确定的目标值(可配合乐观锁) UPDATE account SET balance = 900, version = version + 1 WHERE id = 1 AND version = 3;
通用性最强的做法,支付类接口(Stripe、支付宝开放平台等)都靠它:客户端为「一次业务意图」生成一个唯一键,服务端记录「键 → 首次结果」,之后带同一个键的请求直接返回当初的结果,不再执行业务。
POST /payments HTTP/1.1
Host: api.example.com
Idempotency-Key: 7f2c1a90-3d5e-4c8b-9f11-2a4d6e8b0c31
Content-Type: application/json
{"order_no":"NO202405010001","amount":9900}
要点:
// SET key value NX EX 3600 —— 只有第一次会成功 const ok = await redis.set(`idem:${req.get("idempotency-key")}`, "1", { NX: true, // 仅当 key 不存在时写入 EX: 3600, // 1 小时后自动过期 }); if (!ok) return res.status(409).json({ code: "DUPLICATE" }); // 继续处理业务……
SET NX 是原子操作,能挡住绝大多数并发重复请求;但它只记「来过」,不记「结果」,所以严格场景下还要配一张真正的结果表。
把「重复」变成「不合法」,是业务层最稳的一类写法。支付回调、订单流转全靠它:
// 回调可能被重复推送多次,这里按状态判断,天然幂等 const o = await repo.findByOrderNo(orderNo); if (!o) return res.status(404).end(); if (o.status === "PAID") return res.send("success"); // 已处理过,直接应答 if (o.status !== "UNPAID") return res.status(409).end(); await repo.markPaid(orderNo); // UNPAID -> PAID,只可能发生一次 res.send("success");
INSERT INTO dedup(biz_key) VALUES (?),靠唯一索引报错来判断「已经处理过」;关键是让去重记录与业务写入落在同一个事务里,保证「判断」和「执行」原子。幂等存在的最大理由就是让重试合法。反过来,重试的纪律也很清楚:
GET / PUT / DELETE);对非幂等操作自动重试,等于赌运气。408 超时、429 限流可以例外)。一句话:**幂等负责让重试安全,重试负责让幂等有用。**
| 概念 | 关心什么 | 与幂等的关系 |
|---|---|---|
| 幂等 | 重复执行后状态是否一致 | —— |
| 安全(safe) | 是否改动状态 | 安全的方法一定幂等,反之不然 |
| 可重试 | 失败后能否再来一次 | 幂等是自动重试的前提 |
| 原子性 | 要么全做、要么全不做 | 不同维度:原子不代表重复执行结果一致 |
| 并发安全 | 多个请求同时来会不会互相踩 | 幂等管「重复」,并发安全管「同时」,通常要靠锁 / 唯一索引 / CAS |
| exactly-once | 恰好执行一次 | 工程上一般用「至少一次 + 幂等」逼近 |
| 去重(dedup) | 识别并丢弃重复 | 实现幂等的常见手段,不是同义词 |
特别要盯住并发:两个相同的请求同时到达时,「第二次」还没来得及看到第一次的结果,就可能双双执行成功。带 NX 的 Redis 去重、唯一索引、乐观锁 CAS、行锁——这些才是堵住并发缺口的东西。
| 坑 | 说明 |
|---|---|
| 把「幂等」理解成「响应一样」 | 定义看的是最终状态;DELETE 第二次返回 404 依然幂等 |
| 以为 GET 一定安全 | GET 幂等的前提是服务端真没用它改数据;「GET 触发写入」的接口并不少见 |
UPDATE x = x + 1 当幂等 | 增量更新天生不幂等,要么带幂等键,要么改成赋值 |
| 只用 Redis 去重就高枕无忧 | 键会过期、Redis 可能丢数据;关键业务要有数据库唯一索引兜底 |
| 幂等键由服务端生成 | 每次生成新键等于没有键;必须客户端生成并在重试时复用 |
| 幂等键不绑用户 | 不绑租户 / 用户会串号,还可能被恶意复用 |
| 没记「处理中」状态 | 并发同键请求会穿透两次;要先把键落库标为处理中 |
| 只管请求层,不管消息消费 | MQ 重投不做幂等,前面的重试防护全白做 |
| 去重与业务不在同一事务 | 中间掉电仍会造成重复执行;去重和业务写入要一起提交 |
PUT 幂等吗?POST 呢?→ PUT 幂等,POST 不幂等DELETE 第二次返回 404,还算幂等吗?→ 算,状态没有变化UPDATE account SET balance = balance - 100 怎么改成幂等?→ 改成赋固定值(或乐观锁),并引入唯一键 / 幂等键去重**幂等 = 同一操作执行一次和执行多次,对系统状态的影响相同。它不看响应码,只认最终状态;它的价值在于让「重试」这件不可避免的事变得安全,从而把「至少一次」变成事实上的「恰好一次」。**
mdk height=560 color=#4f46e5
# 幂等 Idempotence
## 是什么
- 执行一次 = 执行多次,最终状态相同
- 看状态,不看响应
- 名字来自数学:f(f(x)) = f(x)
- 赋值天然幂等,自增不幂等
- 重复施加 ≠ 效果累加
## 为什么需要
- 网络超时 → 结果未知
- MQ 至少一次投递,可能重复
- 用户连点、刷新重放表单
- 至少一次 + 幂等 = 事实上的恰好一次
## HTTP 语义
### 幂等
- GET / HEAD / OPTIONS:安全且幂等
- PUT:整体替换,幂等
- DELETE:幂等,状态不再变化
### 非幂等
- POST:提交 / 创建
- PATCH:取决于补丁内容
### 推论
- 安全 ⇒ 幂等,反之不然
- 响应不同不代表不幂等
- DELETE 第二次 404 仍幂等
## 实现手段
### 数据库约束
- 唯一索引 / 唯一键兜底
- ON CONFLICT DO NOTHING
- upsert:ON DUPLICATE KEY UPDATE
### 写法
- 用赋值代替自增
- 乐观锁 version 比对
### 幂等键
- 客户端生成 UUID,重试复用
- 服务端存「键 → 结果」
- 记录「处理中」防并发穿透
- 绑定用户 / 租户,设置 TTL
### 缓存与状态
- Redis SET NX EX 快速去重
- 状态机只允许向前走
- 一次性令牌
- 去重表 / 去重日志,与业务同事务
## 重试
- 幂等让重试变安全
- 超时是「结果未知」,先查证
- 指数退避 + 抖动 + 上限
- 5xx / 408 / 429 可重试,4xx 一般不重试
- 非幂等操作不要自动重试
## 易混概念
- 安全:不改变状态,比幂等更强
- 原子性:不同维度,不代表幂等
- 并发安全:管「同时」,幂等管「重复」
- exactly-once:用至少一次 + 幂等逼近
- 去重:只是手段,不是同义词
## 常见坑
- 以为幂等就是响应一样
- 增量 UPDATE 却当成幂等
- 只靠 Redis,缺少库级兜底
- 幂等键由服务端生成 / 不绑用户
- 消息消费没做幂等
- 去重与业务不在同一事务
相关:get_put_post · redis · mq · 一文讲清楚什么是csrf
返回:代码术语