写客户集成时,假设每个请求都会到两次
超时后重试一次,就可能让客户被扣两次款;Stripe 的建议是用幂等键让服务器认出重发的请求。
要点速览
- 遇到网络错误或 500 时,你无法知道服务器做了什么。用同一个幂等键、同样的参数重试,再通过 Webhook 对账。
- Webhook 可能重复到达,也可能乱序。按事件 ID 去重,永远不要依赖顺序。
- 快速返回 2xx,把重活交给队列,并弄清哪些服务商不会自动重发 Webhook。
周一早上九点,客户的会计发来一张截图:同一笔订单扣了两次款。日志显示,周末网络抖动了一阵,创建支付的请求超时,你的任务按设定老老实实重试了一次。
代码没有语法错误,也从没崩溃。出问题的是一个假设:请求只会到达一次、顺序正确、而且总能得到明确的答复。对前线部署工程师(FDE)来说,这个假设几乎每天都会被打破。
Palantir 对 FDE 岗位的描述是:让工程师嵌入客户团队,解决客户最紧迫的问题。在客户系统内部工作,也意味着你迟早要接触连接这些系统与外部系统的管道。管道搭得扎实,就能赢得信任。
搭得马虎,你就得花一周时间解释为什么数字对不上。
收到错误时,你并不知道发生了什么
先接受一个令人不安的事实。Stripe 的错误处理文档说得很直白:发生网络错误后,客户端无法知道服务器是否收到了请求。写操作收到 500 响应,也必须视为结果不确定,即操作可能执行了,也可能没有。
因此盲目重试很危险,而完全不重试又可能丢单。出路是幂等键(idempotency key):由客户端生成的字符串,最长 255 个字符,Stripe 建议使用 UUID V4。把它附在请求上,服务器就能识别重复提交。
Stripe 的机制很简单:对每个键,它会保存第一次请求的状态码和响应体,即使那次请求失败了也照样保存,之后的每次重试都原样返回这个结果。如果用同一个键搭配不同的参数,幂等层会返回错误,阻止这种失误。
有三个细节新手常常忽略。键可能在 24 小时后被删除,不要把它当作永久记录。所有 POST 请求都接受幂等键,而 GET 或 DELETE 带上键没有任何作用,因为这两种方法本身就是幂等的。
另外,发生网络错误后,Stripe 的建议是用同一个键、同样的参数持续重试,直到服务器返回结果。
正确重写一个支付任务
回到周一那次事故。最关键的改动是:幂等键必须在创建订单时只生成一次,并随订单一起保存,绝不能在每次重试时重新生成。一旦重新生成,每次重试看起来都是一笔新交易,幂等性就彻底失效了。
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)
重试循环单独实现,每次尝试都使用同一个键:
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 头,告诉你要等多久才能发送新请求。服务器给了数字,就照着等,不要自己猜:
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 保证“至少一次”送达,这意味着接收方必须做到幂等。
一个好的处理器按顺序做四件事。
@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 重发三次。如果两项测试后数据依然正确,你就完成了客户永远看不到的那部分工作,而正是这部分决定了客户是否信任你。
这篇文章对你有帮助吗?
感谢你的反馈!
7 个信源
- Idempotent requests (Stripe API Reference)
- Advanced error handling (Stripe Docs)
- Receive Stripe events in your webhook endpoint (Stripe Docs)
- Best practices for using webhooks (GitHub Docs)
- Best Practices (Crossmint Docs, Webhooks)
- Retry-After header - HTTP | MDN · 2025-11-21
- Palantir Technologies - Forward Deployed Software Engineer