FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • 遇到网络错误或 500 时,你无法知道服务器做了什么。用同一个幂等键、同样的参数重试,再通过 Webhook 对账。
  • Webhook 可能重复到达,也可能乱序。按事件 ID 去重,永远不要依赖顺序。
  • 快速返回 2xx,把重活交给队列,并弄清哪些服务商不会自动重发 Webhook。
信息图分为两部分。发送端:订单带有一个只生成一次的幂等键。第 1、2 次尝试超时,第 3 次返回结果,三次都使用同一个键;服务器按键记住结果,客户只被扣款一次。遇到 500 错误时,订单标记为“未知”,发送方等待 Webhook。接收端:Webhook 经过四步:获取原始请求体,校验 HMAC-SHA256 签名(时钟偏差不超过 5 分钟),按事件 ID 去重,然后立即返回 2xx 并推入队列,再由 worker 读取当前状态完成繁重处理。注:Stripe live 模式最长三天内重试 Webhook,GitHub 不会自动重试。
发送时,每次重试都必须使用相同的键和参数;接收时,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 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力为什么一次 JOIN 就让客户营收翻了倍主键正确还不够:先把数据聚合到每个度量的粒度,再连接表,错误才不会出现。