金蝶分步式调出单同步到 MySQL 的实战教程
这个策略解决什么问题
在供应链集成里,「分步式调出单」是一类典型的业务单据:它不是一次性出库,而是把一次调拨拆成多个步骤、多个仓库、多个明细行分别处理。某零售企业的财务和运营团队曾反馈,这类单据只放在金蝶云星空里,下游报表、对账系统和 BI 都看不到明细,口径对不齐,审计时只能人工拉数。
我们的做法是:把金蝶云星空的分步式调出单按增量方式持续同步到 MySQL,让下游分析系统、BI、对账脚本都能直接 SQL 取数。这次讲的就是这个具体策略。
数据流向与字段映射
整体链路是「金蝶云星空 → 轻易云集成平台 → MySQL」,本质上是一个查询 + 写入的闭环。
源端(轻易云里把金蝶云星空注册为一个数据源平台):通过 executeBillQuery 接口,以 POST 方式按条件拉取分步式调出单,关键过滤与字段包括 FBillNo(单据编号)、FSTKTRSOUTENTRY_FEntryID(分录内码)、FBillTypeID(单据类型)、FTransferBizType(调拨业务类型)、FTransferDirect(调拨方向)、FBizType(业务类型)等。
中间层(轻易云):不做复杂加工,但承担三件事——按单据编号和分录内码做去重与幂等、把上游字段透传给目标、把调度节奏解耦开。
目标端 MySQL:用 batchexecute 以 SQL 方式批量写入,主键用 id,上游的 FSTKTRSOUTENTRY_FEntryID、FBillNo 一并存入,下游就能按单据编号聚合,也能按分录内码精确追溯。
| 业务含义 | 金蝶云星空字段 | MySQL 字段 | 处理建议 |
|---|---|---|---|
| 单据编号 | FBillNo | FBillNo | 主键候选,业务对账必用 |
| 分录内码 | FSTKTRSOUTENTRY_FEntryID | FSTKTRSOUTENTRY_FEntryID | 与 FBillNo 联合唯一 |
| 单据类型 | FBillTypeID | FBillTypeID | 直接透传 |
| 调拨业务类型 | FTransferBizType | FTransferBizType | 直接透传 |
| 调拨方向 | FTransferDirect | FTransferDirect | 直接透传 |
| 业务类型 | FBizType | FBizType | 直接透传 |
在轻易云上如何配置
在轻易云数据集成平台里,这个策略通常拆成两个动作:一个查询动作连金蝶,一个写入动作连 MySQL。
源动作要点:接口选 executeBillQuery,请求方式 POST,返回体开启 autoFillResponse,让轻易云自动把响应字段映射成变量,后续动作可以直接用 {{FBillNo}} 这类占位符取值。注意 idCheck 这里设为 false,因为我们不靠轻量云的 ID 校验做唯一性,而是靠下游 MySQL 的 id 主键和 (FBillNo, FSTKTRSOUTENTRY_FEntryID) 联合索引。
目标动作要点:接口选 batchexecute,执行类型 SQL,目标平台选 MySQL,把上游字段一一映射到表字段上,id 由源端 FSTKTRSOUTENTRY_FEntryID 充当,做到幂等。
在轻易云里,编码映射建议放在平台层面的「字段映射」统一维护,不要散落在脚本里。这样金蝶字段名换一次,只改一处。这是轻易云客户常用的「编码映射集中管理」模式。
实施步骤
- 确认增量起点:取 MySQL 中
FBillNo最大值或最近一次同步时间作为起点,先在金蝶端做一次小范围executeBillQuery验证,确认返回结构和字段一致性。 - 配置全量触发:首次上线时,在轻易云上手动触发一次「全量补数」,把历史分步式调出单一次性写入 MySQL,这一步通常放在凌晨业务低峰期。
- 配置调度频率:源端 cron 设为
*/7 * * * *(每 7 分钟查一次),目标端 cron 设为3-59/7 * * * *(错开 3 分钟,避免源和目标同时抢占连接)。源与目标错峰是轻易云上比较稳妥的写法。 - 灰度与监控:观察前 3 天的写入条数、失败率、重复率,在 MySQL 端用
(FBillNo, FSTKTRSOUTENTRY_FEntryID)联合唯一约束做兜底,出现重复就让轻易云根据错误日志重跑对应批次。 - 交付与交接:把调度 cron、字段映射表、异常处理 SOP 一并交给运维,留存轻易云的策略 JSON 备份。
踩坑复盘
- 典型错误:把金蝶的
FBillNo直接当 MySQL 主键。分步式调出单一个编号下有多条分录,单独用FBillNo会丢数据。稳妥做法是用FSTKTRSOUTENTRY_FEntryID做id,再用(FBillNo, FSTKTRSOUTENTRY_FEntryID)做联合唯一。 - 源和目标 cron 完全一样,造成数据库瞬时连接抖动。源查一次、目标写一次,如果同时打过去,MySQL 连接池容易被打满。建议错开 2~5 分钟。
autoFillResponse没开,导致字段没注入变量。这是轻易云上很常见的小坑,源动作里autoFillResponse必须开,否则后续{{FBillNo}}全是空。- 金蝶端的过滤条件没写对,把所有单据类型都拉回来了。分步式调出单有自己的单据类型,务必在
executeBillQuery请求里加FBillTypeID等过滤,避免脏数据灌进 MySQL。 - 没有分阶段,直接全量 + 高频并发。第一次上线很容易「全量正在跑、增量又触发了」。稳妥做法是轻易云里常见的「表头表体分阶段」思路:先单独跑全量,全量结束后再放开增量调度。
适用场景与不适用场景
适用:金蝶云星空作为 ERP 主干,下游有 BI、对账、报表系统需要直接 SQL 访问分步式调出单,且数据量在中大型、需要可追溯到分录级别的场景。
不适用:实时性要求秒级以下(本方案最快 7 分钟一周期);金蝶端业务频繁反向回写 MySQL 字段(本策略只做单向同步);以及没有 MySQL、需要直接走消息队列或 API 给消费方的场景。