API 编排实战:把多系统接口组合成一条业务流水线

场景与目标

目标流水线:每 10 分钟从电商平台拉取已付款订单 → 在金蝶云星空中生成销售出库单 → 出库单审核后回写平台发货状态。涉及三个系统、五个接口,要求:不丢单、不重单、异常可追溯。

第一步:拆解为原子接口调用

先把业务动作翻译成接口清单:

第二步:编排执行顺序与分支

1. 拉取订单分页数据,逐条进入流水线(批量场景先查后写,避免半批失败);
2. 分支一:步骤 2 查到已存在出库单 → 跳过建单,直接进入步骤 5(这是幂等的关键分支);
3. 分支二:校验不通过(如 SKU 未映射)→ 挂起该条,转异常队列,不阻塞后续订单;
4. 步骤 3、4 串行执行,失败时按指数退避重试,超过 3 次转人工;
5. 步骤 5 回写成功后,记录该订单的完成状态。

第三步:关键控制点

幂等设计

平台订单号是整条流水线的幂等键。任何一步重跑,都先按它查询现状再决定动作,保证"重跑多少次结果都一样"。

状态机而非标志位

为每条订单记录状态:已拉取 → 已建单 → 已审核 → 已回写。重试时从断点状态继续,而不是从头再来,避免重复建单。

限流与节流

电商平台和 ERP 都有 QPS 限制。流水线层面要做两件事:分页大小与调度频率匹配(10 分钟窗口内的单量 ÷ 页大小 < 限流阈值);写接口串行化,读接口可并行。

常见坑

• 把"拉取增量"和"处理增量"做成一个事务,一次失败整批回滚——应改为逐条推进 + 断点记录;
• 回写发货依赖"出库单已审核",但审核可能是异步的——步骤 5 前要轮询确认状态,而不是假设上一步成功即终态;
• 忽略时区:平台时间戳是 UTC,ERP 是东八区,增量窗口错位会丢单。