用 Idempotency-Key 防止客户端重试产生重复订单
一张 Postgres 表、一个唯一约束,再加上 409 和 422 的明确规则,让每次重试都返回最初的结果。
要点速览
- 客户端为每个操作生成一个 UUID v4,每次重试都发送同一个键;服务端保存首次执行的状态码和响应体,并在重试时重放。
- 按照 IETF 草案,同一个键配不同载荷返回 422;键仍在处理中则返回 409。
- 唯一约束建在 (user_id, idempotency_key) 这对字段上;调用外部系统的处理函数应拆分为多个原子阶段,并设置恢复点。
设想这样一个场景:客户的 ERP 系统调用你刚交付的 API POST /orders。请求超时,ERP 又调用了一次,结果用户只点了一下,仓库却收到两张订单。你的代码本身没有错,只是它还不会识别重试。
这类 bug 通常要等真实数据跑起来才会暴露,而那时前线部署工程师(FDE)恰好就在客户现场。
Stripe 的 API 文档对幂等的用途说得很清楚:连接失败时,客户端可以放心重复请求,不必担心创建出第二个对象,或者同一次更新被执行两次。
本指南带你在一个下午左右,为任意 POST 接口搭建这套机制。
最终你会得到一张存储键的 Postgres 表、一个包装后的处理函数、一个清理旧键的任务,以及三条证明接口行为正确的 curl 命令。准备工作包括:一个可用的 POST 接口、在 Postgres 中建表的权限,以及 curl。下面的处理函数代码是用类 Python 伪代码写的简化示意,请按你使用的框架自行调整。
键由客户端生成,记忆由服务端负责
Brandur Leach 写过一篇在 Postgres 上实现 Stripe 风格幂等键的指南。他对幂等接口的定义是:无论调用多少次,副作用都只发生一次。要做到这一点,服务端需要一个信号,用来判断两个请求其实是同一个操作。
这个信号由客户端生成。Stripe 工程博客介绍了做法:客户端为某一个操作生成唯一 ID,重试时再次发送同一个 ID。
Stripe 文档建议使用 UUID v4 或其他熵足够的随机字符串,长度不超过 255 个字符,并提醒不要在键中放入敏感数据。IETF 草案 draft-ietf-httpapi-idempotency-key-header 将请求头名称标准化为 Idempotency-Key,适用于本身不具备幂等性的方法,例如 POST 和 PATCH。
据 Stripe 介绍,GET 和 DELETE 按定义已经是幂等的,携带键也没有作用。因此只需包装 POST 接口,如果有 PATCH 接口也一并包装。
第 1 步:一张表,按用户设置唯一约束
CREATE TABLE idempotency_keys (
user_id bigint NOT NULL,
idempotency_key varchar(255) NOT NULL,
request_hash text NOT NULL,
status text NOT NULL DEFAULT 'processing',
response_code int,
response_body jsonb,
created_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (user_id, idempotency_key)
);
最关键的是最后一行。在 Brandur 的设计中,键并非在整张表内唯一,而是在 (user_id, idempotency_key) 这对字段上唯一。两个客户碰巧生成相同的字符串,也不会互相覆盖数据;一个客户也无法靠猜键读取另一个客户的响应。
request_hash 列存放请求体的哈希,用于下文的载荷校验。**检查:**在 psql 中运行 \d idempotency_keys,确认这两列上有唯一索引。
第 2 步:先占住键,再做其他事
请求到达后,第一件事是尝试把键插入表中。这条插入语句同时也是你的锁:
INSERT INTO idempotency_keys (user_id, idempotency_key, request_hash)
VALUES ($1, $2, $3)
ON CONFLICT (user_id, idempotency_key) DO NOTHING
RETURNING status;
如果语句返回了一行,说明这是第一次见到这个键,可以继续往下执行。如果什么都没返回,说明键已存在。这时读取已有的记录,按下表三种情况处理。
| 键已存在时的情况 | 响应 |
|---|---|
| 载荷哈希与已存的哈希不同 | 422:同一个键不能用于不同的载荷 |
status = 'processing' |
409:原始请求仍在执行 |
status = 'done' |
原样重放已存的 response_code 和 response_body |
前两个状态码出自 IETF 草案。草案规定,键不得复用于载荷不同的请求,这种情况下服务端应返回 422。
如果重试在原始请求完成前到达,服务端应返回 409。Stripe 在键被复用时也会比对参数,不一致就返回错误,以发现误用。
第 3 步:保存首次响应,即使它是 500
# 流程的简化示意
def create_order(req):
key = req.headers.get("Idempotency-Key")
if key is None:
return handle(req) # 策略选择:直接放行,或强制要求携带键
errors = validate(req.body)
if errors:
return 400, errors # 校验错误:不保存键
h = sha256(canonical_json(req.body))
row = try_reserve(req.user_id, key, h)
if row is None:
old = load(req.user_id, key)
if old.request_hash != h: return 422, {...}
if old.status == "processing": return 409, {...}
return old.response_code, old.response_body
code, body = handle(req)
save_response(req.user_id, key, code, body) # status = 'done'
return code, body
根据 Stripe 文档,v1 API 会在接口开始执行后,保存某个键首次请求的状态码和响应体,并在每次重试时重放,即使结果是 500 错误也一样。
校验失败的请求,以及与另一个并发执行的请求冲突的请求,都不会保存,客户端可以放心重试。所以上面的代码先做校验,再占住键。
**检查:**一次成功请求之后,SELECT status, response_code FROM idempotency_keys 应返回 done 以及刚才返回的状态码。
第 4 步:调用外部系统时,把工作拆成阶段
上面的代码假设 handle 能在一个事务里干净地跑完。实际上,订单接口往往还要调用支付网关,或者向其他系统发送 webhook。如果进程中途崩溃,这条键记录就会永远卡在 processing。
Brandur 用原子阶段解决这个问题:一个原子阶段是在事务内执行的一组本地状态变更,位于外部系统的状态变更之间。每个阶段结束后,向键记录写入一个恢复点,例如 order_created 或 payment_charged。下次重试读取恢复点,从中断处继续,而不是从头再来。
第一个接口不需要完整的这套机制。把处理函数里的每一次外部调用都列出来:每一次都是阶段边界,每个边界之后都应紧跟一个恢复点。
第 5 步:清理旧键,并用 curl 验证
Stripe 可能在 24 小时后删除键。下面的示例采用这个时间窗口;如果客户的重试周期更长,就把间隔调大,使其超过客户最长的重试窗口,然后设置定时任务:
-- 将 '24 hours' 替换为比客户重试窗口更长的时长
DELETE FROM idempotency_keys
WHERE created_at < now() - interval '24 hours';
接着跑三个场景。第一条命令发送一个正常请求:
curl -i -X POST https://api.example.com/orders \
-H "Idempotency-Key: 6f1d2c3a-8b4e-4f5a-9c7d-1e2f3a4b5c6d" \
-H "Content-Type: application/json" \
-d '{"sku":"A1","qty":2}'
原样再运行一次:应返回同一个订单 id,订单表里也不应多出新行。保留这个键,把 qty 改成 3:结果应为 422。最后换一个新键,在每条命令后加 &,同时发出两条命令。如果处理函数足够慢,其中一条会收到 409。
最常见的错误
最常见的错误是只在键这一列上建唯一约束,漏掉了 user_id。其次是只存键、不存载荷哈希,客户端不小心把一个键复用到另一张订单时,会悄无声息地拿到旧订单的响应。第三是把校验错误也存了下来,客户修正请求后仍然收到同一个 400。
客户端同样容易出错。每次重试都生成新键,就等于完全没有幂等。Stripe 博客建议,重试时把键与指数退避配合使用,并在每个客户端的等待时间里加入少量随机抖动,避免所有客户端在同一时刻打到服务端。
这项技能在客户现场是什么样子
在现场,SQL 只是工作的一半。另一半是和客户的集成团队坐在一起,阅读他们的重试代码,商定由谁、在哪里生成键,以及如何保存,确保重试时复用原来的键。
把上面三条 curl 命令和状态码表摆出来之后,讨论就会从争论是谁的 bug,转向商定一份清晰的 API 契约。
如果你想转向 FDE 工作,可以在个人项目上做一遍这个练习,然后在简历上写清楚具体验证了什么,例如:“为创建订单的 API 加入 Idempotency-Key,测试了重复调用、修改载荷和并发调用”。
浏览招聘启事时,留意那些要求把 API 与客户系统集成的岗位。这正是你在面试中讲这个练习的好时机。
下次有人报告数据重复,你的第一个问题应该是:这次重试带的是原来的键吗?
这篇文章对你有帮助吗?
感谢你的反馈!