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

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

技能指南 · 指南

ERP 同步中途失败,最难的是安全重试

幂等键、事务性发件箱和三方对账,让客户的账目在期末结账时分毫不差。

分享微博

要点速览

  • 重复分录通常来自超时后的重发,所以幂等键必须来自业务 ID,而不是随机数。
  • 交易和发件箱事件写在同一个数据库事务里;429 这类瞬时错误先重试,持续失败才执行补偿。
  • 对账必须区分在途资金(时间差)和真正缺失或出错的资金。
左右两栏对比图。左栏为盲目重试:发送分录、超时、重发,结果是 2 条重复分录。右栏为发送前先检查:记录待处理、发送分录、超时、查询外部 ID(高亮步骤),结果是 1 条分录。
ERP 已经记下分录但响应丢失时,立即重发会生成第二条分录。worker 在首次发送前记录“待处理”,每次重试前先查询外部 ID,分录就只会入账一次。来源:文中的打款同步 worker 场景,依据 Stripe 的幂等性文档。

期末结账第三天,客户的总会计师发来一张截图:ERP 里同一笔打款有两条一模一样的分录,前一天的打款却不见踪影。代码没有崩溃过,日志里写的是“timeout, retrying”,接着是“success”。

为大客户做会计集成的前线部署工程师(FDE)对这种情况并不陌生。对财务团队来说,重复分录不是小 bug:只要有一个数字对不上,他们就不会在账目上签字。

一周时间足以做出一个漂亮的同步演示,但要让客户信任你的系统,它必须在成千上万次网络抖动中始终正确。

决定 ERP 集成质量的有三个问题:交易会不会丢?会不会记两次?中途失败时,账目处于什么状态?再加上客户真正关心的第四个:怎么证明两边一致?

交易在到达 ERP 之前丢失

第一类故障出在自己的服务内部。服务先把交易存进数据库,然后才发出“需要同步”的事件。如果进程恰好在这两步之间退出,记录已经存在,却没人通知同步 worker。Microsoft 把这称为双写问题。

解决办法是事务性发件箱(Transactional Outbox):把交易和事件写入 outbox 表,并放在同一个数据库事务里。Microsoft 的架构文档指出,当业务对象及其事件在同一事务中保存时,系统可以保证不丢数据。

worker 只需读取 outbox,把条目推送到 ERP。无论进程在何时退出,都不会留下缺口。

为什么一次重试会多出一条分录?

回到那张截图。设想这样的过程:worker 发送一条分录,ERP 已经入账,但响应在返回途中丢了。worker 看到超时,于是再发一次。ERP 并不知道这是同一个请求,又记了一条。

Stripe 用幂等键解决这个问题。客户端在创建或更新请求上附带一个键,发生连接错误时可以放心重发,不用担心生成第二个对象或把同一次更新执行两遍。

在 API v1 中,服务端会保存某个键的第一次响应,之后的每次重试都原样返回这个响应,即使第一次响应是 500 错误。

Stripe 的文档还补充了两个细节:键由客户端生成,至少保留 24 小时后删除;用同一个键搭配不同参数的请求会被拒绝,以便发现误用。

这两个细节引出两条规则。第一,键必须从稳定的业务 ID 派生(例如 erp-journal:po_123),绝不能每次发送都用 uuid4() 生成,因为随机键会让重试看起来像一个新请求。

第二,键会过期,而且并非所有 ERP 都提供这种机制,所以不能把去重完全交给 ERP。你必须自己维护一张从键到 ERP 记录 ID 的映射表,更重要的是,要在首次发送之前写入这一行,而不是等响应回来之后。

一个写对了的打款同步 worker

假设每天夜里要把打款推送到 NetSuite。根据 Oracle 的文档,超过并发上限时,NetSuite REST Web Services 会返回 HTTP 429,错误码为 CONCURRENCY_LIMIT_EXCEEDED,消息为“Concurrent request limit exceeded. Request blocked.”

Oracle 建议重新发送请求,重试逻辑由你的代码实现。下面的代码使用一个假设的 erp 封装,其中有一个按外部 ID 查询分录的函数:

def sync_payout(payout_id):
    key = f"erp-journal:{payout_id}"         # 来自业务 ID,而不是随机生成
    row = mapping.get(key)
    if row and row.erp_id:
        return row.erp_id                     # 已确认入账:不再重发
    if row is None:
        mapping.save_pending(key)             # 在首次发送之前写入“待处理”
    for attempt in range(6):
        found = erp.find_by_external_id(key)  # 之前的某次发送可能已经入账
        if found:
            mapping.confirm(key, found.id)
            outbox.mark_done(payout_id)
            return found.id
        try:
            resp = erp.post_journal(build_payload(payout_id),
                                    external_id=key, idempotency_key=key)
        except Timeout:                       # 不确定 ERP 是否已经入账
            sleep(min(2 ** attempt, 60) + random())
            continue                          # 下一轮循环会在发送前再查一次
        if resp.status == 429:                # CONCURRENCY_LIMIT_EXCEEDED:瞬时错误
            sleep(min(2 ** attempt, 60) + random())
            continue
        resp.raise_for_status()
        mapping.confirm(key, resp.id)         # 先确认映射,再清理 outbox
        outbox.mark_done(payout_id)
        return resp.id
    alert_oncall(payout_id, key)              # 重试次数用完:交给人工处理

用这段代码重演那天夜里的情况。发送之前,worker 已经为这个键写了一条“待处理”记录。第一次发送超时,但 ERP 实际上已经入账。worker 捕获 Timeout 异常,等待退避时间,进入下一轮循环。

下一轮循环的第一件事不是重发,而是问 ERP:带这个外部 ID 的分录是否已经存在?答案是存在,于是 worker 只确认映射,然后结束。如果 ERP 支持幂等性,同一个键还能再加一层保护,但这个设计并不依赖它。

进程直接退出、三天后才重启时,“待处理”记录同样重要:worker 看到一条未确认的记录,就一定会先查 ERP 再发送。唯一的前提是把键存进分录上一个可搜索的外部 ID 字段,这个字段应在第一周就和客户商定。

第二步失败了,第一步怎么办?

一笔真实的打款通常要跨几个系统走好几步:创建收入记录、过账分录、标记为已付。没有哪个 ACID 事务能同时覆盖你的平台和 ERP。Saga 模式用一串本地事务来代替:某一步失败时,由一系列补偿事务撤销前面各步的操作。

Saga 中有一个概念叫 pivot 事务,即不可回退点。pivot 之后的步骤必须可重试且幂等,这样即使遇到瞬时错误,saga 也总能到达最终状态。在 ERP 过账流程中,已入账的分录通常就是 pivot。

具体到每个客户,原因最好当作待验证的假设:问问总会计师,分录出错时是直接修改,还是必须做一笔冲销分录。如果它确实是不可回退点,过了这一步就只能向前走。

Microsoft 给出了很实用的优先顺序:先重试瞬时错误;只有某一步反复失败或无法恢复时,才停止并触发补偿;有些失败需要告警,让人来介入。补偿步骤本身也可能失败,所以必须写成可以重跑的幂等命令。

在会计领域,最重要的要求是可审计。Microsoft 要求原始操作和补偿操作能够关联起来,并且可以端到端审计。给原始分录、补偿分录和日志附上同一个关联 ID,审计人员只需一次搜索就能追溯整条链路。

对账是证据,不是额外工作

同步正确还不够,客户需要看到证据。Stripe 的银行对账模型是个很好的模板:每笔打款通过共享的参考键与对应的银行入账匹配,然后标记为 Reconciled(已对账)或 Unreconciled(未对账)。把这个模型扩展成三方:平台、ERP 和银行流水,共用一个键。

最大的陷阱是把时间差当成真正的错误。Stripe 的示例提到,银行通常不在周日入账打款,所以示例中 2 月 4 日(周日)的金额单元格是空的。

如果报告把这类行都标成错误,财务团队就会淹没在误报里,不再信任这份报告。

类别 信号 处理
已匹配 三方都有,金额一致 无需处理
时间差 平台和 ERP 中都有,银行尚未入账 等待,结算周期后再核对
真正的不一致 超过截止时间仍有一方缺失,或金额不同 建工单,按关联 ID 追查

从零搭建,按什么顺序?

到了新客户那里,第一件事是和总会计师坐下来,问清楚哪一步是不可回退点、出错时如何更正。答案会告诉你 pivot 在哪里,补偿步骤应该是什么样子。

接着在数据库里建好 outbox,基于业务 ID 为每一步定义键,选定 ERP 中存放键的外部 ID 字段,再写一个对瞬时错误带重试和退避的 worker。

之后才轮到补偿和告警。对账应从第一周就开始跑,而不是等到期末:上面这份三类报告,是赶在客户之前发现设计缺陷的最快办法。

让财务团队失去信任的错误

最常见的错误是每次发送都生成随机键,幂等性因此形同虚设。紧随其后的是只在响应成功后才写映射,于是恰恰在超时那一刻,映射表是空的。再就是把每个 429 或超时都当成失败,立即执行补偿,而本该先重试。

还有两个。补偿步骤不幂等,重跑一次就补偿两遍。另一个出在沟通上:把每笔尚未到账的金额都报成“不一致”。一份满是误报的报告,客户会记得比十个平稳同步的夜晚更久。

简历上怎么写这项技能

简历上一行“NetSuite 集成”几乎什么也说明不了。要写清楚你如何设计幂等同步、处理部分失败、搭建三方对账,以及在多少次期末结账中客户无需手工修改任何一行。

面试时,“ERP 已经入账但响应丢了”这个场景是一个简短的故事,能说明你会在故障发生之前就考虑它。

下次有人说“重试一下就行”,不妨问他:用哪个键重试?再次发送之前,问过 ERP 了吗?

这篇文章对你有帮助吗?

6 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力选文档解析器,30 页客户文档胜过任何排行榜一个下午就能搭好的按字段打分脚本,让 FDE 凭实测准确率选解析器,而不是看榜单或凭直觉。