# 一张 Postgres 表，修好演示里藏着的双写漏洞

> 事件与订单在同一事务中写入，再交给中继投递；接收方做去重，重试也不会产生重复。

原文: https://fdetimes.net/zh/guides/transactional-outbox-postgres-python/

设想客户现场有这样一段代码：把订单存进 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，也不需要单独的队列。

```sql
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 语句必须位于同一个事务块内。

```python
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 文档说明，使用这个选项时，无法立即加锁的行会被跳过，可用于多个消费者读取类队列表时避免锁竞争。

```python
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。

**要点:** outbox 只保证事件不丢；要避免重复，接收方必须自己去重。

这就是 `Idempotency-Key` 请求头直接使用事件 ID 的原因。重复投递无法删除，但可以让它无害。

## 更好的版本：每个事件一个事务

重复无法避免，但因为一个错误就重发 30 个事件，未免浪费。最简单的改法是逐个事件提交：每个事务只锁一行，发送、标记、提交。

```python
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 对应的事件是否已经处理过。如果接收端点也由你来写，或者客户允许你在他们的系统前面加一层缓冲，可以这样做：

```sql
CREATE TABLE processed_events (
  event_id     uuid PRIMARY KEY,
  processed_at timestamptz NOT NULL DEFAULT now()
);
```

```python
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 表无限增长。部分索引能让轮询查询保持快速，但仍然需要一个定时任务清理已发送的行，例如：

```sql
DELETE FROM outbox WHERE sent_at < now() - interval '7 days';
```

这里的 7 天只是示例。原则是你的保留时间要长于接收方的键保留时间，这样排查重复投递时还有数据可以比对。

## 在客户现场，outbox 往往始于一句抱怨

通常是这样一句话：“时不时有订单没进到财务系统。”第一件事是找出所有先写数据库、紧接着调用外部的代码，然后问客户他们的端点如何处理重复请求。

阅读 FDE 或集成工程师岗位的职位描述时，留意 “at-least-once”、“idempotency”、“webhook” 和 “CDC” 这类字眼。简历上写一句“用事务性 outbox 替换双写，并通过中途杀进程测试证明事件不丢、不重复处理”，远比泛泛的 “event-driven” 有说服力。

一个只包含这四个步骤、两个中继版本和一个故障模拟脚本的小仓库，值得带去面试。面试官会问中继中途挂掉会怎样，而你已经用代码准备好了答案。

**本周动手试试:**

- 在本地 Postgres 上创建 orders、outbox 和 processed_events 三张表，运行创建订单的函数，检查两张表要么同时多一行，要么同时为空。
- 在 POST 之后、UPDATE 之前杀掉中继，确认接收方只处理了一次该事件。
- 打开客户现场一个在线运行的集成，找出先写数据库、紧接着调用 API 的代码：那就是第一个适合引入 outbox 的地方。

## 信源

- [Pattern: Transactional outbox](https://microservices.io/patterns/data/transactional-outbox)

- [Reliable Microservices Data Exchange With the Outbox Pattern](https://debezium.io/blog/2019/02/19/reliable-microservices-data-exchange-with-the-outbox-pattern/)

- [PostgreSQL Documentation: SELECT](https://www.postgresql.org/docs/current/sql-select.html)

- [Idempotent requests | Stripe Documentation](https://docs.stripe.com/idempotency)
