代码术语:幂等

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

代码术语:幂等 [2026/10/16 11:43] – 创建 张叶安代码术语:幂等 [2026/10/16 11:44] (当前版本) – 补全「幂等」词条:定义、HTTP 语义、实现手段、重试与常见坑,并加入思维导图 张叶安
行 1: 行 1:
-1+====== 一文讲清楚:幂等(Idempotence) ====== 
 + 
 +**幂等(idempotent / idempotence)** 说的是:**同一个操作执行一次和执行多次,对系统最终状态造成的影响是一样的。** 换言之,「重发一次」不会带来「多做一次」的后果——在网络会超时、消息会重投、用户会连点两次的世界里,这是几乎一切可靠系统的第一道纪律。 
 + 
 +先记住判断口径:**看状态,不看响应。** 一个操作是否幂等,只取决于它把服务端数据改成了什么,与它返回 200 还是 409、返回一个对象还是两个对象都无关。 
 + 
 +===== 1. 从数学名字说起 ===== 
 + 
 +这个词来自数学:满足 ''f(f(x)) = f(x)'' 的函数就是幂等函数,例如绝对值 ''|x|''、''min(x, 0)''——连做两次和做一次没有区别。 
 + 
 +搬到工程里,语义被弱化了,但骨架没变:**「重复施加」不等于「效果累加」**。 
 + 
 +<code javascript> 
 +// 非幂等:每调用一次,余额就多 100 
 +function addBalance(balance) { return balance + 100; } 
 + 
 +// 幂等:无论调用多少次,结果都停在这个值上 
 +function setBalance() { return 500; } 
 +</code> 
 + 
 +分水岭在于这个操作是「**写入一个确定的结果**」还是「**基于当前值做增量**」。前者天然幂等,后者必须靠额外手段才能幂等。 
 + 
 +===== 2. 为什么到处都在讲幂等 ===== 
 + 
 +因为现实里有三件事无法避免: 
 + 
 +  * **网络不可靠**:请求发出去了,响应没回来。客户端并不知道服务端到底执行没执行——这就是「结果未知」,此时重试也不是、不重试也不是。**幂等让重试变成一个安全动作。** 
 +  * **消息至少投递一次(at-least-once)**:绝大多数 MQ 的默认语义是「不丢,但可能重复」。消费端不做幂等,就会重复扣款、重复发货、重复发短信。 
 +  * **用户会连点**:双击提交、刷新后重新提交表单、F5 重放 POST。 
 + 
 +一个值得背下来的等式: 
 + 
 +> **at-least-once 投递 + 消费端幂等 = 事实上的恰好一次(effectively-once)** 
 + 
 +与其追求代价高昂的「精确一次投递」,业界更常见的做法是把重复挡在业务侧。 
 + 
 +===== 3. HTTP 世界里的幂等 ===== 
 + 
 +HTTP 规范(RFC 9110)规定了各方法的幂等性,这是所有 API 设计的公共约定: 
 + 
 +^ 方法 ^ 安全(不改状态) ^ 幂等 ^ 说明 ^ 
 +| ''GET'' / ''HEAD'' | 是 | 是 | 只读;可被爬虫、预取、浏览器回退任意重放 | 
 +| ''OPTIONS'' | 是 | 是 | 探测能力 | 
 +| ''PUT'' | 否 | **是** | 用请求体**整体替换**目标资源:同样的 PUT 发 N 次,资源都是那个样子 | 
 +| ''DELETE'' | 否 | **是** | 删掉就不存在了:第一次 200/204,第二次通常 404,但**服务端状态相同** | 
 +| ''POST'' | 否 | **否** | 语义是「提交 / 创建」,发 N 次就可能创建 N 条记录 | 
 +| ''PATCH'' | 否 | 通常否 | 看补丁内容:''{"name":"张三"}'' 幂等,''{"balance":{"+":100}}'' 不幂等 | 
 + 
 +两条容易考的推论: 
 + 
 +  * **安全的方法一定幂等,幂等的方法不一定安全。** 「安全」(safe)比幂等更强;DELETE 是幂等的,但它确实改数据。 
 +  * **响应不同不等于不幂等。** DELETE 第二次返回 404 很正常,规范只要求**最终状态的效果一致**;重复 PUT 返回 200 还是 201 也不影响幂等性。 
 + 
 +方法层面的细节可对照 [[get_put_post]]。另外注意:规范认为 ''DELETE'' 幂等,前提是接口老老实实删除「**这个 URL 指向的那个资源**」;如果有人把接口写成「删除最新一条记录」,那它就已经破坏幂等性了——**这是接口的锅,不是定义的锅。** 
 + 
 +===== 4. 让它幂等的几种手段 ===== 
 + 
 +==== 4.1 数据库层:用约束兜底 ==== 
 + 
 +唯一索引是把「幂等」写进数据模型的最简单办法:重复插入直接违反约束,什么都不会发生。 
 + 
 +<code sql> 
 +-- 幂等插入: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;    -- 冲突时什么都不改 
 +</code> 
 + 
 +==== 4.2 用「赋值」代替「自增」 ==== 
 + 
 +<code sql> 
 +-- 非幂等:重试一次就多扣一次 
 +UPDATE account SET balance = balance - 100 WHERE id = 1; 
 + 
 +-- 幂等:写入确定的目标值(可配合乐观锁) 
 +UPDATE account SET balance = 900, version = version + 1 
 +WHERE id = 1 AND version = 3; 
 +</code> 
 + 
 +==== 4.3 幂等键(Idempotency-Key) ==== 
 + 
 +通用性最强的做法,支付类接口(Stripe、支付宝开放平台等)都靠它:**客户端为「一次业务意图」生成一个唯一键**,服务端记录「键 → 首次结果」,之后带同一个键的请求直接返回当初的结果,不再执行业务。 
 + 
 +<code http> 
 +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} 
 +</code> 
 + 
 +要点: 
 + 
 +  * 键由**客户端**生成(通常是 UUID),**重试时必须保持不变**; 
 +  * 服务端要同时记录「处理中」和「已完成」两种状态,否则并发同键请求会双双穿透到业务; 
 +  * 记录要有 TTL(例如 24 小时),不然这张表会无限膨胀; 
 +  * 键要和**用户 / 租户**绑定,防止被猜到或跨用户复用导致结果串号。 
 + 
 +==== 4.4 Redis 快速去重 ==== 
 + 
 +<code javascript> 
 +// 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" }); 
 +// 继续处理业务…… 
 +</code> 
 + 
 +''SET NX'' 是原子操作,能挡住绝大多数并发重复请求;但它只记「来过」,不记「结果」,所以严格场景下还要配一张真正的结果表。 
 + 
 +==== 4.5 状态机:只允许向前走 ==== 
 + 
 +把「重复」变成「不合法」,是业务层最稳的一类写法。支付回调、订单流转全靠它: 
 + 
 +<code javascript> 
 +// 回调可能被重复推送多次,这里按状态判断,天然幂等 
 +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"); 
 +</code> 
 + 
 +==== 4.6 一次性令牌 / 去重表 ==== 
 + 
 +  * **一次性令牌**:下单页带一个一次性 token,提交后作废,重复提交直接拒绝(和防 CSRF 是同一套思路)。 
 +  * **去重表**:''INSERT INTO dedup(biz_key) VALUES (?)'',靠唯一索引报错来判断「已经处理过」;关键是让去重记录与业务写入落在**同一个事务**里,保证「判断」和「执行」原子。 
 + 
 +===== 5. 幂等和重试是孪生兄弟 ===== 
 + 
 +幂等存在的最大理由就是**让重试合法**。反过来,重试的纪律也很清楚: 
 + 
 +  * 只有**幂等**的操作才适合自动重试(''GET'' / ''PUT'' / ''DELETE'');对非幂等操作自动重试,等于赌运气。 
 +  * **超时 ≠ 失败。** 超时的语义是「**结果未知**」,直接重试可能造成两次执行,所以要么先查询确认,要么带上幂等键。 
 +  * 重试要**退避**(指数退避 + 抖动)并设上限,避免把已经过载的服务打死。 
 +  * 服务端 5xx 或超时 → 可重试;4xx 一般没意义(''408'' 超时、''429'' 限流可以例外)。 
 + 
 +> 一句话:**幂等负责让重试安全,重试负责让幂等有用。** 
 + 
 +===== 6. 容易混淆的几个概念 ===== 
 + 
 +^ 概念 ^ 关心什么 ^ 与幂等的关系 ^ 
 +| **幂等** | 重复执行后状态是否一致 | —— | 
 +| **安全(safe)** | 是否改动状态 | 安全的方法一定幂等,反之不然 | 
 +| **可重试** | 失败后能否再来一次 | 幂等是自动重试的前提 | 
 +| **原子性** | 要么全做、要么全不做 | 不同维度:原子不代表重复执行结果一致 | 
 +| **并发安全** | 多个请求同时来会不会互相踩 | 幂等管「重复」,并发安全管「同时」,通常要靠锁 / 唯一索引 / CAS | 
 +| **exactly-once** | 恰好执行一次 | 工程上一般用「至少一次 + 幂等」逼近 | 
 +| **去重(dedup)** | 识别并丢弃重复 | 实现幂等的常见手段,不是同义词 | 
 + 
 +特别要盯住**并发**:两个**相同**的请求同时到达时,「第二次」还没来得及看到第一次的结果,就可能双双执行成功。带 ''NX'' 的 Redis 去重、唯一索引、乐观锁 CAS、行锁——这些才是堵住并发缺口的东西。 
 + 
 +===== 7. 常见坑 ===== 
 + 
 +^ 坑 ^ 说明 ^ 
 +| 把「幂等」理解成「响应一样」 | 定义看的是最终状态;DELETE 第二次返回 404 依然幂等 | 
 +| 以为 GET 一定安全 | GET 幂等的前提是服务端真没用它改数据;「GET 触发写入」的接口并不少见 | 
 +| ''UPDATE x = x + 1'' 当幂等 | 增量更新天生不幂等,要么带幂等键,要么改成赋值 | 
 +| 只用 Redis 去重就高枕无忧 | 键会过期、Redis 可能丢数据;关键业务要有数据库唯一索引兜底 | 
 +| 幂等键由服务端生成 | 每次生成新键等于没有键;必须客户端生成并在重试时复用 | 
 +| 幂等键不绑用户 | 不绑租户 / 用户会串号,还可能被恶意复用 | 
 +| 没记「处理中」状态 | 并发同键请求会穿透两次;要先把键落库标为处理中 | 
 +| 只管请求层,不管消息消费 | MQ 重投不做幂等,前面的重试防护全白做 | 
 +| 去重与业务不在同一事务 | 中间掉电仍会造成重复执行;去重和业务写入要一起提交 | 
 + 
 +===== 8. 30 秒自测 ===== 
 + 
 +  * 幂等看的是什么?→ **最终状态,而不是响应内容** 
 +  * ''PUT'' 幂等吗?''POST'' 呢?→ **PUT 幂等,POST 不幂等** 
 +  * ''DELETE'' 第二次返回 404,还算幂等吗?→ **算,状态没有变化** 
 +  * 「至少一次 + 幂等」等于什么?→ **事实上的恰好一次** 
 +  * ''UPDATE account SET balance = balance - 100'' 怎么改成幂等?→ **改成赋固定值(或乐观锁),并引入唯一键 / 幂等键去重** 
 +  * 超时之后能直接重试 POST 吗?→ **不能,先查证结果,或带上幂等键** 
 + 
 +===== 9. 一句话记住 ===== 
 + 
 +> **幂等 = 同一操作执行一次和执行多次,对系统状态的影响相同。它不看响应码,只认最终状态;它的价值在于让「重试」这件不可避免的事变得安全,从而把「至少一次」变成事实上的「恰好一次」。** 
 + 
 +```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]] 
 + 
 +---- 
 + 
 +返回:[[代码术语]] 

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • 代码术语/幂等.1792122207.txt.gz
  • 最后更改: 2026/10/16 11:43
  • 由 张叶安