架构与系统设计 / 系统课时
消费幂等应该在哪一层做
消费幂等应该在哪一层做
订单确认事件被重投后,订单状态可能没变,却又多生成了一张履约单。本篇从这类重复副作用出发,比较四种幂等手段,并通过故障注入验证:去重记录与业务结果必须一起成功或一起回滚。
学习目标
- 区分消息重复与业务动作重复,选择正确的幂等标识。
- 判断唯一键、去重表、业务状态机和接口幂等键各自保护什么。
- 实现去重与业务写入的原子提交,确定消息确认的时机。
先定义不能重复的业务效果
消费幂等不是让处理函数只执行一次,而是让同一业务动作重复到达时,不再产生额外业务效果。至少一次投递允许消息被再次交付,所以判断标准应是业务结果,而不是消费者被调用了几次。([microservices.io][1])
本例约定一张订单只生成一张首次履约单。相同 event_id 再次到达是消息重复;生产者误用新事件号重复确认同一订单,则是业务动作重复。只检查事件号,挡不住后一种情况。
四种手段分别守住什么
| 手段 | 适合保护的对象 | 关键边界 |
|---|---|---|
| 业务唯一键 | 一单一张履约单、一次操作一条流水 | 键应代表业务动作,不能仅用随机自增主键 |
| 去重表 | 某个逻辑订阅对同一事件的处理 | 去重记录必须与业务写入同事务 |
| 业务状态机 | 只允许从待确认进入已确认 | 状态判断与修改要原子化,副作用不能脱离事务 |
| 接口幂等键 | 对外部接口的同一操作重试 | 服务端须识别并保存结果,同键不能换参数 |
去重表通常采用 (handler, event_id) 联合唯一键。这里的 handler 是稳定的逻辑处理器名称,不是进程号或实例名;不同副本共享去重范围,不同订阅则可以分别处理同一事件。([microservices.io][1])
本例组合前三种手段,是因为既要识别消息重投,又要约束首次履约。若业务本身只需按唯一业务键插入一行,可以先用唯一约束解决,不必为了“标准架构”额外建立去重表。
让幂等跟随业务事务
建议让消费适配器负责解析、调用和确认;应用服务编排事务;领域规则决定允许的状态迁移;数据库约束兜住并发。这样消息入口和补偿入口能复用同一业务操作,而不是各自维护一份判断逻辑。
事务内先尝试写入去重记录,再修改业务数据,最后一起提交。提交失败,记录也应回滚;提交成功但确认丢失,重投才能识别已完成结果。不要采用两个彼此独立的“先记成功、再做业务”事务。([microservices.io][1])

“先查询不存在,再插入”不是并发保护:两个消费者可能同时查不到。应由唯一约束裁决竞争,并只处理目标唯一键的冲突,不能把所有数据库异常都解释成重复消息。([PostgreSQL][2])
用一次故障注入验证原子性
下面是完整 Python 脚本,适用于 Python 3.11 及以上,底层 SQLite 需支持 UPSERT,即 3.24.0 及以上。本例只用内存数据库,不连接消息代理;订单号和事件号都是固定测试数据。([Python documentation][3])
import sqlite3
# 仅用于本地实验;生产环境应使用持久化数据库。
db = sqlite3.connect(":memory:", isolation_level=None)
db.executescript("""
CREATE TABLE inbox (
handler TEXT NOT NULL,
event_id TEXT NOT NULL,
order_id TEXT NOT NULL,
PRIMARY KEY (handler, event_id)
);
CREATE TABLE orders (id TEXT PRIMARY KEY NOT NULL, status TEXT NOT NULL);
CREATE TABLE shipments (order_id TEXT PRIMARY KEY NOT NULL);
INSERT INTO orders VALUES ('order-a', 'PENDING');
""")
def consume(event_id: str, order_id: str, fail: bool = False) -> str:
with db:
# 显式开始事务;去重记录不能早于业务结果单独提交。
db.execute("BEGIN IMMEDIATE")
inserted = db.execute(
"""INSERT INTO inbox VALUES ('confirm-order', ?, ?)
ON CONFLICT(handler, event_id) DO NOTHING""",
(event_id, order_id),
).rowcount
if inserted == 0:
saved = db.execute(
"SELECT order_id FROM inbox WHERE handler=? AND event_id=?",
("confirm-order", event_id),
).fetchone()
if saved != (order_id,):
raise ValueError("event_id reused with different payload")
return "duplicate"
# 状态迁移失败不一定是重复,也可能是订单不存在或已取消。
changed = db.execute(
"UPDATE orders SET status='CONFIRMED' WHERE id=? AND status='PENDING'",
(order_id,),
).rowcount
if changed == 0:
status = db.execute(
"SELECT status FROM orders WHERE id=?", (order_id,)
).fetchone()
if status != ("CONFIRMED",):
raise ValueError("invalid order state")
return "already-confirmed"
db.execute("INSERT INTO shipments VALUES (?)", (order_id,))
# 在所有写入之后制造故障,验证三张表一起回滚。
if fail:
raise RuntimeError("simulated failure")
return "applied"
try:
consume("evt-a", "order-a", fail=True)
except RuntimeError:
assert db.execute("SELECT status FROM orders").fetchone() == ("PENDING",)
assert db.execute("SELECT COUNT(*) FROM inbox").fetchone() == (0,)
assert db.execute("SELECT COUNT(*) FROM shipments").fetchone() == (0,)
print("first: rolled-back")
print("retry:", consume("evt-a", "order-a"))
print("replay:", consume("evt-a", "order-a"))
print("new-id:", consume("evt-b", "order-a"))
print("orders:", db.execute("SELECT id, status FROM orders").fetchall())
print("inbox:", db.execute("SELECT COUNT(*) FROM inbox").fetchone()[0])
print("shipments:", db.execute("SELECT COUNT(*) FROM shipments").fetchone()[0])
db.close()预期输出:
first: rolled-back
retry: applied
replay: duplicate
new-id: already-confirmed
orders: [('order-a', 'CONFIRMED')]
inbox: 2
shipments: 1第一次异常发生在三项写入之后,断言验证状态和两张表一起回滚。with db 会在正常退出时提交已开启事务,在异常退出时回滚;因此调用方拿到正常返回结果时,事务已经结束。([Python documentation][3])
同一事件重投返回 duplicate;更换事件号后,状态规则返回 already-confirmed,不会再创建履约单。去重表有两条记录而履约单只有一张,说明消息身份与业务动作身份不是同一回事。
代码只把已确认状态视为本场景的已完成结果;订单不存在或处于其他状态时会抛错。不能将所有状态不匹配都当作幂等成功,否则可能吞掉需要修复的业务异常。
外部副作用与上线边界
本地事务不能回滚已经成功的外部调用。需要发送后续事件时,可以在本地事务中保存 Outbox 待发送记录,再独立投递;Outbox 解决可靠发送,接收方仍须处理重复。([microservices.io][4])
调用支持幂等的外部接口时,同一业务操作重试应复用同一个键,并核对参数和有效期。例如 Stripe 会比较同键请求参数,键被清理后再次使用可能被视为新请求,不能假设所有接口永久去重。
上线前还应验证多实例并发重投、提交成功但尚未确认时进程退出,以及同键不同载荷。去重记录保留期应覆盖实际重试和历史重放窗口;补发、退款等合法新动作则需要独立业务键,不能被“一单一次”的规则误伤。
幂等的主边界应围绕业务事务建立,而不是只放在消息监听器的一段缓存判断里。真正的验收结果是重复投递没有制造额外副作用,同时失败后的重试仍能完成原来的业务动作。