# 用 Idempotency-Key 防止客户端重试产生重复订单

> 一张 Postgres 表、一个唯一约束，再加上 409 和 422 的明确规则，让每次重试都返回最初的结果。

原文: https://fdetimes.net/zh/guides/idempotency-key-post-duplicate-orders/

设想这样一个场景：客户的 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 步：一张表，按用户设置唯一约束

```sql
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 步：先占住键，再做其他事

请求到达后，第一件事是尝试把键插入表中。这条插入语句同时也是你的锁：

```sql
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

```python
# 流程的简化示意
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 小时后删除键。下面的示例采用这个时间窗口；如果客户的重试周期更长，就把间隔调大，使其超过客户最长的重试窗口，然后设置定时任务：

```sql
-- 将 '24 hours' 替换为比客户重试窗口更长的时长
DELETE FROM idempotency_keys
WHERE created_at < now() - interval '24 hours';
```

接着跑三个场景。第一条命令发送一个正常请求：

```bash
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 与客户系统集成的岗位。这正是你在面试中讲这个练习的好时机。

下次有人报告数据重复，你的第一个问题应该是：这次重试带的是原来的键吗？

**本周动手试试:**

- 挑一个你交付过的 POST 接口，按模板创建 idempotency_keys 表，并跑一遍本指南中的三项 curl 检查
- 重新阅读客户端的重试代码：确认每次尝试都复用同一个键，并使用带抖动的指数退避
- 在集成文档中加一小节，说明 Idempotency-Key 请求头，以及客户可能收到的 409 和 422 状态码

## 信源

- [Idempotent requests | Stripe API Reference](https://docs.stripe.com/api/idempotent_requests)

- [The Idempotency-Key HTTP Header Field (draft-ietf-httpapi-idempotency-key-header-08)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)

- [Implementing Stripe-like Idempotency Keys in Postgres](https://brandur.org/idempotency-keys)

- [Designing robust and predictable APIs with idempotency](https://stripe.com/en-US/blog/idempotency)
