一张 Postgres 表,修好演示里藏着的双写漏洞
事件与订单在同一事务中写入,再交给中继投递;接收方做去重,重试也不会产生重复。
要点速览
- 没有哪个事务能同时覆盖你的数据库和客户的系统,所以事件必须先写进你自己的数据库。
- 中继可能把同一个事件发送不止一次:“事件不丢”实际上指的是至少一次(at-least-once)投递。
- 只有接收方按事件 ID 去重(例如借助 Idempotency-Key),才能做到“不重复”。
设想客户现场有这样一段代码:把订单存进 Postgres,提交,然后调用客户 ERP 的 webhook。如果进程恰好在这两行之间挂掉,订单已经存在,ERP 却永远收不到通知。把顺序反过来,风险也跟着反过来:ERP 收到了一张你的数据库已经回滚的订单。
这就是双写(dual-write)问题。Debezium 博客说得很直白:不存在一个能同时覆盖服务数据库和 Apache Kafka 的共享事务。换成客户的系统也是一样,而且更难,因为它不归你控制。
对前线部署工程师(FDE)来说,这是“演示时能跑”的集成里最典型的 bug。本指南用 Postgres 和 Python 从零搭建一个事务性 outbox,可以直接带到客户现场使用。
要构建什么,需要先准备什么
按 microservices.io 的描述,outbox 只回答一个问题:如何原子地更新数据库并发送消息。服务先把消息存进数据库,与业务数据处于同一事务,之后再由中继负责发送。
你需要一个本地运行的 Postgres、Python 3 和一个 Postgres 驱动。下面的代码采用 psycopg 3 的写法,配合 httpx 这类 HTTP 客户端。这是用于学习的精简版本:没有日志、重试退避和配置项,上生产环境之前需要自己补上。
第 1 步:outbox 表放在你自己的数据库里
按 Debezium 的说法,核心思路是在服务自己的数据库里放一张 “outbox” 表。不需要中间 broker,也不需要单独的队列。
CREATE TABLE orders (
id uuid PRIMARY KEY,
customer_id text NOT NULL,
status text NOT NULL
);
CREATE TABLE outbox (
id uuid PRIMARY KEY,
aggregate_id uuid NOT NULL,
event_type text NOT NULL,
payload jsonb NOT NULL,
created_at timestamptz NOT NULL DEFAULT now(),
sent_at timestamptz
);
CREATE INDEX outbox_unsent ON outbox (created_at)
WHERE sent_at IS NULL;
检查:在 psql 中执行 \d outbox,应能看到 outbox_unsent,这是一个只覆盖未发送行的部分索引。id 列就是事件 ID,接收方之后会用它去重。
第 2 步:在同一事务中写入订单和事件
整个模式都建立在这一步之上。两条 INSERT 语句必须位于同一个事务块内。
import uuid, json
def create_order(conn, customer_id):
order_id = uuid.uuid4()
event_id = uuid.uuid4()
with conn.transaction():
conn.execute(
"INSERT INTO orders (id, customer_id, status) VALUES (%s, %s, 'created')",
(order_id, customer_id),
)
conn.execute(
"INSERT INTO outbox (id, aggregate_id, event_type, payload) "
"VALUES (%s, %s, 'order_created', %s)",
(event_id, order_id, json.dumps({"order_id": str(order_id), "customer_id": customer_id})),
)
return order_id
测试方法:在两条 INSERT 之间故意抛出一个异常。正确的结果是 orders 和 outbox 都为空。如果出现有订单没事件,或者反过来,说明你用的是两个事务,而不是一个。
注意,这个函数不发起任何网络调用。它只碰你自己的数据库,所以很快,也不会因为客户的 API 慢而卡住。
第 3 步:基于 SKIP LOCKED 的轮询中继
microservices.io 列出了实现中继的两种方式:事务日志追踪(CDC)和轮询发布(polling publisher)。只用 Python 和 Postgres 时,轮询是合理的起点,因为它不需要额外的基础设施。
要运行多个 worker,就需要 SKIP LOCKED。Postgres 文档说明,使用这个选项时,无法立即加锁的行会被跳过,可用于多个消费者读取类队列表时避免锁竞争。
def relay_once(conn, http, url, batch=50):
with conn.transaction():
rows = conn.execute(
"SELECT id, event_type, payload FROM outbox "
"WHERE sent_at IS NULL ORDER BY created_at "
"LIMIT %s FOR UPDATE SKIP LOCKED",
(batch,),
).fetchall()
for event_id, event_type, payload in rows:
resp = http.post(
url,
json={"id": str(event_id), "type": event_type, "data": payload},
headers={"Idempotency-Key": str(event_id)},
timeout=10,
)
resp.raise_for_status()
conn.execute("UPDATE outbox SET sent_at = now() WHERE id = %s", (event_id,))
把这个函数放进循环,配一个短暂的 sleep。检查:开两个终端运行两个 worker,创建 200 个订单,然后在接收端计数。两个 worker 应各自拿到不同的一部分,谁也不必等谁。
这里有意做了简化:整批数据放在一个长事务里,每次 HTTP 调用期间都持有行锁。Postgres 文档还提醒,SKIP LOCKED 给出的数据视图并不一致,所以只应用于 outbox 这类类队列表,不要用于普通查询。
为什么“事件不丢”仍然意味着“可能重复”
用上面的版本走一遍具体场景。一批有 50 个事件,前 30 个 POST 成功,第 31 个返回 500 错误。raise_for_status 抛出异常,事务回滚,前面 30 次 UPDATE 也随之丢失。
下一次轮询时,客户已经收到的这 30 个事件会被再发一遍。进程在 POST 和 UPDATE 之间被杀掉,结果也一样。microservices.io 讲清了后果:中继可能把一条消息发布不止一次,所以消费方必须幂等,例如记录已经处理过的消息 ID。
这就是 Idempotency-Key 请求头直接使用事件 ID 的原因。重复投递无法删除,但可以让它无害。
更好的版本:每个事件一个事务
重复无法避免,但因为一个错误就重发 30 个事件,未免浪费。最简单的改法是逐个事件提交:每个事务只锁一行,发送、标记、提交。
def relay_one(conn, http, url):
with conn.transaction():
row = conn.execute(
"SELECT id, event_type, payload FROM outbox "
"WHERE sent_at IS NULL ORDER BY created_at "
"LIMIT 1 FOR UPDATE SKIP LOCKED"
).fetchone()
if row is None:
return False
event_id, event_type, payload = row
resp = http.post(
url,
json={"id": str(event_id), "type": event_type, "data": payload},
headers={"Idempotency-Key": str(event_id)},
timeout=10,
)
resp.raise_for_status()
conn.execute("UPDATE outbox SET sent_at = now() WHERE id = %s", (event_id,))
return True
重跑前面的场景:前 30 个事件的 sent_at 已经提交,只有第 31 个回到队列。在 POST 和 UPDATE 之间杀掉进程,现在只会重复一个事件。注意,只用 ORDER BY created_at 时,失败的事件会被立即重试,所以需要加上退避。
这个版本在等待 HTTP 时仍然锁着一行。如果客户的 API 很慢,下一步是“先认领”:用一个短事务给这一行打上带时间戳的认领标记并提交,在事务之外发送,之后再更新 sent_at。这样你得自己加一列,并制定规则回收认领太久的行,所以只在确有必要时才这么做。
第 4 步:接收方按事件 ID 去重
在 Debezium 的示例中,处理函数做的第一件事就是检查这个 UUID 对应的事件是否已经处理过。如果接收端点也由你来写,或者客户允许你在他们的系统前面加一层缓冲,可以这样做:
CREATE TABLE processed_events (
event_id uuid PRIMARY KEY,
processed_at timestamptz NOT NULL DEFAULT now()
);
def handle_event(conn, event):
with conn.transaction():
cur = conn.execute(
"INSERT INTO processed_events (event_id) VALUES (%s) ON CONFLICT DO NOTHING",
(event["id"],),
)
if cur.rowcount == 0:
return # 已处理过,跳过
apply_business_change(conn, event)
关键在于,去重的 INSERT 和业务变更必须在同一个事务里。把它们拆开,你就亲手造了一个微型的双写问题。
重跑上面的场景:在 POST 之后立刻杀掉中继。中继重启后,processed_events 里这个事件仍然只有一行,业务变更也只执行了一次。
客户已有幂等 API 时,参考 Stripe
很多时候你碰不到客户的代码。这时要问清楚对方的 API 是否支持幂等键(idempotency key)。Stripe 是很好的参照:由客户端生成键,便于服务端识别重试;Stripe 建议使用 V4 UUID,键最长可达 255 个字符。
Stripe 会保存每个键对应的第一次响应,重试时返回同一个响应,包括 500 错误。键在 24 小时后被清理;如果旧键带着不同的参数再次出现,Stripe 会返回错误,防止误用。
这两个细节可以转化为向客户提的两个问题。他们的键保留多久?如果你的中继宕机时间超过这个窗口,重发的事件会被当成新事件。另外,千万不要每次重试都生成新键:键属于事件,而不属于请求。
常见错误
最常见的错误是“为了省时间”在 create_order 里直接调用 API,把 outbox 当成兜底。这又回到了双写。第二个错误是用自增的请求 ID 当幂等键,导致每次重试都产生一个新键。
第三个错误是任由 outbox 表无限增长。部分索引能让轮询查询保持快速,但仍然需要一个定时任务清理已发送的行,例如:
DELETE FROM outbox WHERE sent_at < now() - interval '7 days';
这里的 7 天只是示例。原则是你的保留时间要长于接收方的键保留时间,这样排查重复投递时还有数据可以比对。
在客户现场,outbox 往往始于一句抱怨
通常是这样一句话:“时不时有订单没进到财务系统。”第一件事是找出所有先写数据库、紧接着调用外部的代码,然后问客户他们的端点如何处理重复请求。
阅读 FDE 或集成工程师岗位的职位描述时,留意 “at-least-once”、“idempotency”、“webhook” 和 “CDC” 这类字眼。简历上写一句“用事务性 outbox 替换双写,并通过中途杀进程测试证明事件不丢、不重复处理”,远比泛泛的 “event-driven” 有说服力。
一个只包含这四个步骤、两个中继版本和一个故障模拟脚本的小仓库,值得带去面试。面试官会问中继中途挂掉会怎样,而你已经用代码准备好了答案。
这篇文章对你有帮助吗?
感谢你的反馈!