「这个接口是幂等的」——这句话在评审里出现的频率很高,但十次里有六次,说的人真正想表达的是「重复调用不会报错」。
这两件事完全不同。不报错只是表面,幂等要求的是重复执行产生与单次执行相同的效果。中间差了整整一层副作用管理。
一个真实的漏洞
某次批量任务重试,导致同一笔订单被扣了两次款。代码长这样:
def process_order(order_id):
order = repo.get(order_id)
if order.status == "paid":
return # 这里以为已经幂等了
gateway.charge(order.amount) # 外部调用
order.status = "paid"
repo.save(order)
问题在于 charge 和 save 之间没有原子性。如果进程在扣款成功后崩溃,订单状态还是 pending,重试时会再扣一次。
幂等的三个层次
| 层次 | 做法 | 能防住什么 |
|---|---|---|
| 请求层 | 幂等键去重 | 同一个请求被重复提交 |
| 状态层 | 状态机 + 条件更新 | 并发写入互相覆盖 |
| 副作用层 | 外部调用的唯一凭证 | 扣款、发短信、写第三方系统 |
三层缺一层,就有漏洞。
请求层:幂等键
客户端生成一个唯一键,服务端存起来。同一个键第二次进来直接返回第一次的结果。
def handle(req):
key = req.headers.get("Idempotency-Key")
if not key:
raise BadRequest("missing idempotency key")
cached = store.get(key)
if cached:
return cached
result = do_business(req)
store.set(key, result, ttl=86400)
return result
注意 store.set 必须在业务成功后执行,否则失败的请求会被缓存成成功。
状态层:条件更新
不要「读-判断-写」,要用带条件的原子更新。
UPDATE orders
SET status = 'paid'
WHERE id = ?
AND status = 'pending';
检查受影响行数:返回 0 说明状态已经变了,本次是重复操作,直接退出。
这比在应用层加锁简单得多,也不需要分布式锁。
副作用层:最容易被忽略
数据库能回滚,外部调用不能。所以每次调用外部系统都要带一个业务唯一标识。
gateway.charge(
amount=order.amount,
idempotency_key=f"order-{order.id}-charge",
)
支付网关收到相同的 key 会返回第一次的结果,不会重复扣款。如果对方不支持幂等键,就只能自己在本地记录「已调用」的状态,并且做好对账。
补偿不能代替幂等
很多人第一反应是「出了问题补偿一下就行」。但补偿本身也是副作用,也需要幂等。
- 补偿脚本跑两遍,会不会退两次钱
- 补偿失败后重试,怎么知道上次是不是已经成功
- 补偿和正向流程并发,谁先谁后
没想清楚这三个问题,补偿只是把问题推后。
自愈的前提
自愈系统真正依赖的不是重试次数,而是「任何一步都能安全重放」。这要求:
- 每个操作有唯一标识,可以判断是否执行过
- 状态流转是单向的,不会来回跳
- 外部调用有幂等凭证或可对账的记录
满足这三条,重试才是安全的;不满足,重试就是在放大故障。
幂等是设计出来的,不是测出来的。等到线上开始重复扣款,再补检查逻辑,成本会高一个数量级。
上线前检查清单
- 写接口是否接受幂等键?键的存储 TTL 是否覆盖最大重试窗口?
- 状态更新是否带条件?是否检查了受影响行数?
- 所有外部调用是否带唯一凭证?对方是否真的支持?
- 消息队列的消费端是否做了去重?重复投递会怎样?
- 补偿脚本能否重复执行?
这五条过一遍,比写一百个重试分支有用。