# 写客户集成时，假设每个请求都会到两次

> 超时后重试一次，就可能让客户被扣两次款；Stripe 的建议是用幂等键让服务器认出重发的请求。

原文: https://fdetimes.net/zh/guides/idempotent-api-webhook-integrations/

周一早上九点，客户的会计发来一张截图：同一笔订单扣了两次款。日志显示，周末网络抖动了一阵，创建支付的请求超时，你的任务按设定老老实实重试了一次。

代码没有语法错误，也从没崩溃。出问题的是一个假设：请求只会到达一次、顺序正确、而且总能得到明确的答复。对前线部署工程师（FDE）来说，这个假设几乎每天都会被打破。

Palantir 对 FDE 岗位的描述是：让工程师嵌入客户团队，解决客户最紧迫的问题。在客户系统内部工作，也意味着你迟早要接触连接这些系统与外部系统的管道。管道搭得扎实，就能赢得信任。

搭得马虎，你就得花一周时间解释为什么数字对不上。

## 收到错误时，你并不知道发生了什么

先接受一个令人不安的事实。Stripe 的错误处理文档说得很直白：发生网络错误后，客户端无法知道服务器是否收到了请求。写操作收到 500 响应，也必须视为结果不确定，即操作可能执行了，也可能没有。

因此盲目重试很危险，而完全不重试又可能丢单。出路是幂等键（idempotency key）：由客户端生成的字符串，最长 255 个字符，Stripe 建议使用 UUID V4。把它附在请求上，服务器就能识别重复提交。

Stripe 的机制很简单：对每个键，它会保存第一次请求的状态码和响应体，即使那次请求失败了也照样保存，之后的每次重试都原样返回这个结果。如果用同一个键搭配不同的参数，幂等层会返回错误，阻止这种失误。

有三个细节新手常常忽略。键可能在 24 小时后被删除，不要把它当作永久记录。所有 POST 请求都接受幂等键，而 GET 或 DELETE 带上键没有任何作用，因为这两种方法本身就是幂等的。

另外，发生网络错误后，Stripe 的建议是用同一个键、同样的参数持续重试，直到服务器返回结果。

## 正确重写一个支付任务

回到周一那次事故。最关键的改动是：幂等键必须在创建订单时**只生成一次**，并随订单一起保存，绝不能在每次重试时重新生成。一旦重新生成，每次重试看起来都是一笔新交易，幂等性就彻底失效了。

```python
def create_payment(order):
    key = order.idempotency_key          # UUID v4，创建订单时生成，存入数据库
    payload = {
        "amount": order.amount,
        "currency": order.currency,
        "metadata[order_id]": order.id,  # 供后续对账使用
    }
    return send_with_retry(payload, key, order)
```

重试循环单独实现，每次尝试都使用同一个键：

```python
def send_with_retry(payload, key, order):
    for attempt in range(6):
        try:
            r = requests.post(PAYMENTS_URL, data=payload,
                              headers={"Idempotency-Key": key}, timeout=10)
        except (requests.ConnectionError, requests.Timeout):
            time.sleep(2 ** attempt)     # 用同一个键重试
            continue
        if r.status_code == 429:
            time.sleep(retry_after(r, attempt))
            continue
        if r.status_code >= 500:
            mark_indeterminate(order)    # 等待 Webhook/对账
            return None
        return r
    mark_indeterminate(order)
    return None
```

429 分支值得留意。限流是集成工作的日常，根据 MDN 的说明，429 响应可能带有 Retry-After 头，告诉你要等多久才能发送新请求。服务器给了数字，就照着等，不要自己猜：

```python
def retry_after(r, attempt):
    wait = r.headers.get("Retry-After")
    return int(wait) if wait and wait.isdigit() else 2 ** attempt
```

500 分支不做盲目重试。订单被标记为“结果不确定”，真相从另一个方向到来：Webhook，加上把交易与订单对应起来的 `order_id` 元数据。这也是 Stripe 推荐的处理方式：通过 Webhook 和元数据对账。

## Webhook 会迟到、重复、乱序

反方向更难，因为别人什么时候调用你，你控制不了。Stripe 明确指出，端点偶尔会多次收到同一事件，事件也可能乱序到达。Crossmint 的文档说，其 Webhook 保证“至少一次”送达，这意味着接收方必须做到幂等。

一个好的处理器按顺序做四件事。

```python
@app.post("/webhooks/payments")
def receive():
    raw = request.get_data()                       # 原始请求体，不做解析
    sig = request.headers.get("Stripe-Signature")
    try:
        event = stripe.Webhook.construct_event(raw, sig, WEBHOOK_SECRET)
    except Exception:
        return "", 400                             # 签名无效或已过期
    if not processed_events.insert_if_absent(event["id"]):
        return "", 200                             # 已处理过：跳过
    queue.enqueue(handle_event, event["id"])
    return "", 200                                 # 立即返回 2xx
```

第一步是拿到原始请求体。Stripe 通过 `Stripe-Signature` 头用 HMAC-SHA256 为每个 Webhook 签名，校验时需要一字不差的原始请求体。如果框架已经解析并重新序列化，哪怕改动一个空格，签名就会失效，你还会白白花半天去怀疑密钥。

签名中还包含时间戳，用于防范重放攻击。Stripe 的库默认允许该时间戳与当前时间最多相差 5 分钟。实际情况是，如果客户服务器的时钟偏差足够大，即使密钥完全正确，所有 Webhook 都会被拒绝。

接下来按事件 ID 去重，然后在做任何重活之前返回 2xx。Stripe 建议通过异步队列处理事件，以吸收突发流量。在 worker 中，不要假设“已支付”事件总在“已创建”事件之后到达。更稳妥的做法是先读取对象的当前状态，再更新订单。

**要点:** 把每个请求都当作可能执行两次，把每个事件都当作可能乱序到达；只有在这两种情况下都正确的代码，才能上生产环境。

## 每家服务商的承诺都不同，要仔细读

FDE 赢得信任的地方就在这里：把每家服务商的文档读透，弄清你的系统宕机时由谁负责重发。

| | Stripe | GitHub |
|---|---|---|
| 响应期限 | 在执行繁重逻辑之前返回 2xx | 必须在 10 秒内返回 2XX |
| 投递失败时 | Live 模式最长三天内自动重发，采用指数退避 | 不会自动重新投递 |
| 宕机后你要做的事 | 应对积压的旧事件一次性涌入 | 服务器恢复后自行重新投递漏掉的 Webhook |

这个差异决定了架构。用 Stripe，宕机两小时通常能自愈，前提是处理器扛得住涌入的事件。用 GitHub，如果没有重新投递的脚本或流程，漏掉的数据就永远丢了，交给客户的运维手册必须把这一步写清楚。

## 反复出现的错误

最常见的是在重试循环里生成新的幂等键，让保护完全失效。紧随其后的是复用旧键却改了参数，比如修正了金额，然后对报错感到意外。参数变了就是新操作，新操作需要新键。

第二种是把 500 当作“肯定失败”，换一个键重新创建交易。第三种是把全部业务逻辑塞进 Webhook 处理器：写数据库、调用 ERP、发邮件。ERP 一次响应慢，就会超时，服务商把这次投递记为失败，重发循环随之开始。

最后一种很少有人关注：没有对账机制。代码写得再好，也需要一个定时任务，通过元数据比对两边的状态，因为总有一天会漏掉某个事件。

## 把这项技能写进简历

阅读 FDE 或解决方案工程师的岗位描述时，留意“integrations”“webhooks”“customer systems”“data pipelines”这类词。看到它们，就准备好一个关于幂等和 Webhook 的故事，证明你处理过真实的故障，而不只是调过 API。

所以不要写“集成了 Stripe”，要写具体：引入幂等键和基于 Webhook 的对账，消除重复交易；将 Webhook 处理器改为基于队列的处理，并按事件 ID 去重。面试中如果聊到，就讲清事故经过、原因，以及你如何证明它不会再次发生。

本周练习：拿一个你正在运行的集成，在 POST 进行到一半时拔掉网线，再把同一个 Webhook 重发三次。如果两项测试后数据依然正确，你就完成了客户永远看不到的那部分工作，而正是这部分决定了客户是否信任你。

**本周动手试试:**

- 打开 Stripe 测试模式，用同一个 Idempotency-Key 发送两次相同的 POST，第三次用同一个键但改变金额，记录三次响应。
- 搭建一个小型 Webhook 端点，包含签名校验、processed_events 表和队列，然后把同一事件重发三次，确认它只被处理一次。
- 翻出一个你写过的集成，检查一下：POST 超时时，你的代码会怎么做？

## 信源

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

- [Advanced error handling (Stripe Docs)](https://docs.stripe.com/error-low-level)

- [Receive Stripe events in your webhook endpoint (Stripe Docs)](https://docs.stripe.com/webhooks)

- [Best practices for using webhooks (GitHub Docs)](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks)

- [Best Practices (Crossmint Docs, Webhooks)](https://docs.crossmint.com/introduction/platform/webhooks/best-practices)

- [Retry-After header - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After)

- [Palantir Technologies - Forward Deployed Software Engineer](https://jobs.lever.co/palantir/5168e8fd-fec1-4fea-b7a1-81bdaea65850)
