幂等键的设计:为什么「先查后写」不等于幂等

举报
yd_299686804 发表于 2026/11/19 14:46:18 2026/11/19
【摘要】 写一个「创建订单」的接口,客户端超时了,于是重试一次。最基本的直觉是:服务端记一下这个请求的标识,重复请求直接返回上次的结果。 于是代码长这样: python if key in SEEN: return 200, SEEN[key] SEEN[key] = result return 201, result 看起来没问题。但在并发下它不成立。 我把三种实现各跑了一遍,同一个...
# 幂等键的设计:为什么「先查后写」不等于幂等 ## 一、现象 写一个「创建订单」的接口,客户端超时了,于是重试一次。最基本的直觉是:**服务端记一下这个请求的标识,重复请求直接返回上次的结果。** 于是代码长这样: ```python if key in SEEN: return 200, SEEN[key] # ... 干活 ... SEEN[key] = result return 201, result ``` 看起来没问题。**但在并发下它不成立。** 我把三种实现各跑了一遍,同一个 key 发 8 个并发请求,差别非常明显。 先说清楚我的测试台:本地起一个 `ThreadingHTTPServer`,端点是 `POST /charge`,请求头带 `Idempotency-Key`。服务端维护一个 `charges` 计数器和一个 `SEEN` 字典。客户端用 8 个线程并发打同一个 key。 三种模式: - `none`:完全无视 `Idempotency-Key`; - `naive`:上面那段「先查后写」,且**故意把耗时工作放在锁外面**(这是真实业务里最常见的形态); - `atomic`:**先在锁内占位,再干活**。 ## 二、三种实现的实测输出 同一 key(`PAY-A-ORDER-0001`)并发 8 次: ```text mode=none key=same n=8 distinct_bodies=8 replayed=0 executed=8 statuses=[201] bodies=[{'amount': 100, 'charge_id': 1}, ..., {'amount': 100, 'charge_id': 8}] mode=naive key=same n=8 distinct_bodies=8 replayed=0 executed=8 statuses=[201] bodies=[{'amount': 100, 'charge_id': 1}, ..., {'amount': 100, 'charge_id': 8}] mode=atomic key=same n=8 distinct_bodies=1 replayed=7 executed=1 statuses=[200, 201] bodies=[{'amount': 100, 'charge_id': 1}] ``` 读法: - **`none` 和 `naive` 完全一样**:8 个并发请求产生 8 个不同的 `charge_id`,服务端计数器涨了 8。也就是说,**naive 版的幂等保护在并发下一次都没生效**。 - **`atomic` 只有一个 `charge_id`**,其余 7 个是重放(`Idempotent-Replay: true`,状态码 200 而不是 201)。 `naive` 为什么全军覆没?因为检查(`if key in SEEN`)和写入(`SEEN[key] = result`)之间有一段窗口。如果这段窗口里还有「干活」的部分(真实业务里就是写数据库、调下游),那么: ```text 线程 1: 检查 → 不存在 → [干活 20ms] → 写入 线程 2: 检查 → 不存在 → [干活 20ms] → 写入 ``` 两个线程都通过了检查,都会执行「干活」。**检查和写入必须在同一个临界区里,中间不能有让出控制权的操作。** `atomic` 版的做法就是:**在锁内先占位,把 key 写进字典,然后再干活。** ```python # atomic:先占位,再干活 with LOCK: if key in SEEN: return 200, SEEN[key] STATE["charges"] += 1 body = {"charge_id": STATE["charges"], "amount": 100} SEEN[key] = body return 201, body ``` 对比 `naive` 版的差别只有一处——**「干活」这段被挪到了锁外面**,但占位提前了。 服务器最终状态: ```text mode=none → {"charges": 16, "distinct_keys": 0} mode=naive → {"charges": 16, "distinct_keys": 9} mode=atomic → {"charges": 9, "distinct_keys": 9} ``` `naive` 那行的 `distinct_keys: 9` 特别说明问题:8 个并发同 key 请求 + 8 个不同 key 请求,一共 16 次请求,但字典里只有 9 个 key——**同 key 的 8 次并发里有 7 次被后来的写入覆盖掉了**,所以字典里只剩 1 个。数据既重复扣了,又对不上账。 ## 三、为什么这段约束会咬人 因为**串行测试永远测不出来**。 我用同一个 key 串行发 8 次,`naive` 模式的表现是完全正确的: ```text sequential 8x same key: distinct_bodies=1 statuses=[200] ``` 一次 201,七次 200,全部返回同一个 `charge_id`。**从黑盒看,这个实现是完美的幂等。** 只有在并发下才会崩。 这就是它咬人的地方:幂等键的保护逻辑,**结构上必须和并发测试一起验证**。你写完一个幂等接口,用 `curl` 敲两遍确认「第二次返回了同样的结果」,这只能证明「顺序重放没问题」——而真实世界里的重试,恰恰来自网络抖动、客户端超时、网关重发,这些都会导致**多个请求几乎同时到达**。 另一个咬人的点是**返回值语义**。`atomic` 模式返回的状态码是 `[200, 201]`:第一次 201(Created),重放 200(OK)。这是有意的——**201 表示「资源被创建了」,200 表示「这次没有创建,只是把上次的结果给你」**。如果重放也返回 201,客户端会以为「又创建了一个」,然后把 201 解释成「新增成功」,统计口径就错了。 ## 四、协议层怎么规定这件事 这不是我拍脑袋定的。IETF 有一份正在走标准的文档专门定义这个请求头:`draft-ietf-httpapi-idempotency-key-header-07`(2025 年 10 月 15 日发布,作者 J. Jena、S. Dalal,Standards Track,2026 年 4 月 18 日过期)。原文在 https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html 。 文档 §2.2「Uniqueness of Idempotency Key」写得很直接: > The idempotency key MUST be unique and MUST NOT be reused with another request with a different request payload. > > Uniqueness of the key MUST be defined by the resource owner and MUST be implemented by the clients of the resource. It is RECOMMENDED that a UUID [ RFC4122 ] or a similar random identifier be used as an idempotency key. 给的头长这样: ```http Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324" ``` §2.6「Idempotency Enforcement」把重试分成两种情况,这是我最看重的一段: > **Retry** — The request was retried after the original request completed. The resource SHOULD respond with the result of the previously completed operation, success or an error. > > **Concurrent Request** — The request was retried before the original request completed. The resource SHOULD respond with a resource conflict error. **「原请求已完成的重试」和「原请求还在处理中的重试」,期望的响应是不一样的。** 前者返回上次结果(我实验里的 200),后者返回冲突错误(409)。这个区分我在实验里没有实现(我的 atomic 版对并发中的重试直接返回了已占位的结果),但它解释了为什么「原样返回上次结果」这个做法在生产里需要小心——**如果你还没做完,就返回一个「已完成」的结果,等于骗了客户端**。 §2.4「Idempotency Fingerprint」给出了指纹的做法——同一个 key 配上不同的请求体,应当被识别出来: > If there is an attempt to reuse an idempotency key with a different request payload, the resource SHOULD reply with a HTTP 422 status code (422 定义在 RFC9110 §15.5.21。) 指纹可以这么算: > - Checksum of the entire request payload. > - Checksum of selected element(s) in the request payload. > - Field value match for each field in the request payload. > - Field value match for selected element(s) in the request payload. > - Request digest/signature. §2.3 还提到过期策略: > The resource MAY require time based idempotency keys to be able to purge or delete a key upon its expiry. The resource SHOULD define such expiration policy and publish it in the documentation. 以及 §2.7 的错误处理: > If the Idempotency-Key request header is missing for a documented idempotent operation requiring this header, the resource SHOULD reply with an HTTP 400 status code with body containing a link pointing to relevant documentation. ## 五、一个真实实现里,幂等是怎么落地的 上面是协议和我的实验台。再看一个**生产形态**的实现长什么样——一个公开的鸿蒙案例仓(`harmony-practice-center/todo_list`,main 分支,commit `859fb35`,https://gitcode.com/harmony-practice-center/todo_list )实现的是多端云同步的待办清单,云侧是 8 个云函数 + RDS MySQL。 它的云函数 `harmony_cloud/functions/taskCreate/index.js` 里,幂等是靠**客户端生成的 UUID 主键 + 数据库唯一键 upsert** 实现的: ```javascript // 幂等:同 UUID 重复创建视为更新(客户端重试安全) await pool.query( `INSERT INTO tasks (id, user_id, title, done, priority, due_date, deleted, created_at, updated_at) VALUES (?, ?, ?, 0, ?, ?, 0, ?, ?) ON DUPLICATE KEY UPDATE title = VALUES(title), priority = VALUES(priority), due_date = VALUES(due_date), deleted = 0, updated_at = VALUES(updated_at)`, [task_id, user.user_id, v.title, v.priority, v.due_date, now, now] ); ``` 这个实现里有三个点值得注意: **第一,幂等键由客户端生成。** 函数注释写得很清楚: ```javascript /** * taskCreate:新建任务(幂等 upsert,客户端生成 UUID 主键) * POST body:{ token, task_id, title, priority, due_date } * - task_id:客户端生成 UUID(v4) */ ``` 这和 IETF 文档 §2.2 说的「It is RECOMMENDED that a UUID or a similar random identifier be used as an idempotency key」是一致的。**服务端不生成幂等键**——因为重试发生在客户端,服务端没有机会在两次请求之间「认出」它们是同一次操作。 **第二,`ON DUPLICATE KEY UPDATE` 让幂等落到了数据库的原子性上。** 这比「先查后写」强的地方在于:**「查」和「写」在同一条 SQL 语句里,由数据库保证原子性**,根本不存在检查与写入之间的窗口。这正是我在实验里 `atomic` 模式想要的效果,只不过生产环境把它下沉到了存储引擎。 **第三,幂等不等于授权。** 同一个函数里,紧挨着 upsert 之前有一段归属校验: ```javascript // 归属校验:客户端可提交任意 task_id(含他人正在用/已删任务的 UUID)。 // 若该 id 已被他人占用却直接走 upsert,会改写他人 title/priority/due_date 并把 deleted 复位——越权。 // 先查该 id 归属,非本人则拒绝(保持 README §6「按会话解析出的 user_id 过滤」一致)。 const [owner] = await pool.query('SELECT user_id FROM tasks WHERE id = ?', [task_id]); if (owner.length > 0 && owner[0].user_id !== user.user_id) { return respond(200, { code: 1, message: '任务不存在或无权操作' }); } ``` **这一段是我在本节最想强调的。** 幂等键是客户端给的,所以它**不是信任凭据**。如果只做 upsert 而不校验归属,攻击者只要猜到(或者拿到)别人的 `task_id`,就能用 upsert 改写别人的任务内容、还把 `deleted` 复位。 **顺序也不能反。** 归属校验必须在 upsert 之前,否则「先改后查」就已经产生副作用了。 ## 六、可复现的最小实现 上面那个测试台的核心逻辑,完整贴出来(`server.py`,只依赖标准库): ```python import json, threading, time from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer STATE = {"charges": 0} SEEN = {} LOCK = threading.Lock() MODE = {"mode": "atomic"} # none | naive | atomic def handle_post(key): if MODE["mode"] == "none": with LOCK: STATE["charges"] += 1 return 201, {"charge_id": STATE["charges"], "amount": 100} if MODE["mode"] == "naive": if key in SEEN: # ← 检查 return 200, SEEN[key] time.sleep(0.02) # ← 干活(窗口在这里) with LOCK: STATE["charges"] += 1 body = {"charge_id": STATE["charges"], "amount": 100} SEEN[key] = body # ← 写入 return 201, body with LOCK: # ← 占位与写入在同一临界区 if key in SEEN: return 200, SEEN[key] STATE["charges"] += 1 body = {"charge_id": STATE["charges"], "amount": 100} SEEN[key] = body return 201, body class H(BaseHTTPRequestHandler): protocol_version = "HTTP/1.1" def log_message(self, *a): pass def do_POST(self): key = self.headers.get("Idempotency-Key") status, body = handle_post(key) raw = json.dumps(body).encode() self.send_response(status) self.send_header("Content-Type", "application/json") self.send_header("Content-Length", str(len(raw))) self.send_header("Idempotent-Replay", "false") self.end_headers() self.wfile.write(raw) ``` 配套的客户端(`client.py`): ```python import json, urllib.request from concurrent.futures import ThreadPoolExecutor def one(i): req = urllib.request.Request("http://127.0.0.1:8731/charge", data=b'{"amount":100}', method="POST") req.add_header("Idempotency-Key", "PAY-A-ORDER-0001") with urllib.request.urlopen(req) as r: return r.status, json.loads(r.read()) with ThreadPoolExecutor(max_workers=8) as ex: res = list(ex.map(one, range(8))) bodies = {json.dumps(b, sort_keys=True) for _, b in res} print("distinct_bodies =", len(bodies)) # atomic 模式应为 1 ``` 跑法: ```bash python3 server.py atomic & python3 client.py ``` 把 `server.py` 的 `MODE` 改成 `naive`,再跑一遍——`distinct_bodies` 会从 1 变成 8。**这就是幂等保护有没有真正生效的唯一判据。** 想看原始报文,可以用裸 socket 连一次: ```text --- 第 1 次发送 --- HTTP/1.1 201 Created Content-Type: application/json Content-Length: 31 Idempotent-Replay: false {"charge_id": 1, "amount": 100} --- 第 2 次发送同一 key --- HTTP/1.1 200 OK Content-Type: application/json Content-Length: 31 Idempotent-Replay: true {"charge_id": 1, "amount": 100} ``` ## 七、代价与不适用场景 - **占位方案会占住内存。** 我这个实现把 `SEEN` 字典永久留着,真实系统里必须有过期清理。IETF 文档 §2.3 说的就是这个:定义过期策略,并写进文档里。**没有过期策略的幂等表就是个内存泄漏。** - **「先占位再干活」在干活失败时需要回滚。** 我的实现里干活和占位是同一步(只是计数器自增),所以没有这个问题。真实场景是「占位成功、干活失败」,这时候要么把占位标记为失败态、让后续重试能重新执行,要么返回 500 让客户端重试——**这两种策略的取舍取决于业务是否允许「结果未知」**。 - **本文只覆盖单个资源实例。** 我的实验是一个进程内的字典。**多实例部署时,幂等表必须共享**(数据库唯一索引 / Redis SETNX),否则请求打到 A 实例、重试打到 B 实例,等于没有幂等。这一点我的实验完全没有覆盖。 - **客户端也有一份责任。** 文档 §2.2 明说 key 的唯一性「MUST be implemented by the clients of the resource」。客户端必须为**每一次业务操作**生成新的 key;拿同一个 key 去请求两个不同的业务动作,是客户端的 bug,服务端只能靠指纹(422)来兜。 - **指纹计算有成本。** §2.4 列的五种做法里,「整个请求体的 checksum」在请求体大的时候不便宜;「只匹配部分字段」则可能漏检——**选择哪几个字段参与指纹,本身就是一个业务决定**,不是纯技术选择。 - **第五节那个案例仓的实现只覆盖了一部分情形。** 它的 `taskCreate` 是幂等 upsert + 归属校验,但它**没有实现请求指纹**(IETF §2.4 的 422 场景),也**没有实现「原请求处理中」时的 409**(§2.6 的 Concurrent Request 场景)——同一个 UUID 在两次并发请求同时到达时,行为取决于数据库唯一键的竞争,函数不会显式返回冲突。另外它的幂等键是「任务主键」而不是「一次操作」的标识,所以**同一个任务被反复编辑不会复用幂等键**。我只是借它说明生产形态长什么样,不是说它是一个完整的幂等框架。 - **我没读这份文档的每一节。** 上面引用的是 §2.1~§2.4、§2.6、§2.7 的原文,仍然处于 Internet-Draft 阶段(文档页脚写着「This note is to be removed before publishing as an RFC」),**定稿前条款可能变**。另外规范里的 SHOULD / MAY 是建议而非强制,具体状态码要按你自己的接口约定来。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。