对账系统仓库主数据从吉客云同步到 MySQL的完整策略教程

这个策略解决什么问题

在一次实际项目中,某零售企业要把吉客云里的仓库主数据搬到对账系统的 MySQL 库里,做后续的库存与单据对账。表面上看,「仓库」字段不多,推一推就行。但只要业务跑起来,问题会接踵而来:编码格式不统一、停用与删除状态混在一起、增量起点写死导致漏数据、自增主键和业务唯一键没分清导致脏数据累积。我们在客户现场用轻易云数据集成平台(Qeasy)承接了这块,落成一个独立的同步策略——「对账系统——仓库信息」。

数据流向与字段映射

数据流向是单向的:吉客云 → 轻易云中间层 → MySQL 对账库。源端通过吉客云的 RESTful 接口 erp.warehouse.get 拉取仓库,目标端通过 MySQL 的 execute 接口把数据写入 warehouse 表。

下面这张对照表是策略的核心,字段命名我做了一定简化,实际项目中请以脱敏后的源字段名为准:

目标字段(MySQL)	源字段(吉客云)	映射类型	说明
warehouse_code	warehouseCode	DIRECT	业务唯一编码
warehouse_name	warehouseName	DIRECT	仓库名称
warehouse_type	warehouseTypeCode / warehouseTypeName	DIRECT	1=自建自用,2=委外托管,3=供应商虚拟仓
source_Id	warehouseId	DIRECT	吉客云主键,用于对账、回写、增量匹配
status	isBlockup / isDelete 推导	TRANSFORM	0=禁用,1=启用
create_by	固定常量	CONSTANT	如 `system`
create_time	gmtCreate 或当前时间	CONSTANT / DIRECT	时间戳需转 datetime
reconciliation_type	业务常量	CONSTANT	对账系统业务字段

source_Id 是这套策略里最关键的一列,本质是「跨系统对照字段」,所有增量、对账、回写都靠它。

在轻易云上如何配置

在轻易云数据集成平台上,这条策略被拆成「源端读 + 目标端写」两条管道。

源端配置要点:

元数据里 api 选 erp.warehouse.get,method=POST,type=QUERY。
number 填 warehouseCode,id 填 warehouseId,idCheck=true,这一项务必打开,后面避免重复插入全看它。
分页参数 pageIndex 从 0 开始,pageSize 默认给 50;如果一次返回里夹杂着已删除/已停用记录,在源端请求里通过 code、name 这类可选条件做收敛。
增量条件 gmtModifiedStart、gmtModifiedEnd 用来圈定本次拉取的时间窗,起始时间固定 2024-03-20 00:00:00,结束时间用 {{CURRENT_TIME|datetime}}。

目标端配置要点:

元数据选 MySQL 平台的 execute,buildModel=true。
main_sql 是一段预编译的 INSERT INTO ... VALUES (...),占位符用 <{字段名: }> 的写法,字段顺序与上面对照表保持一致。
main_params 是绑定参数的对象,字段命名与源端返回字段一一对应,这样源端的 JSON 一进来就能直接套进 SQL。

实施步骤

我们把这个策略分三步走,每一步都用轻易云的调度能力承接。

第一步,首次全量初始化。增量起点先用一个固定的早于业务开始的日期(本方案里是 2024-03-20 00:00:00),把吉客云里所有「未删除」的仓库一次性灌进对账库。这一轮的目标是先把表撑起来,不计较重复。

第二步,启用增量。在轻易云里把这个策略的调度改为每 20 分钟跑一次(*/20 * * * *),并把 gmtModifiedStart 替换成 {{LAST_SYNC_TIME|datetime}},真正按修改时间窗口拉新增与变更。

第三步,常态化校验与回补。每天再加一个低峰时段的兜底调度,用全量条件再跑一次,与增量结果做差集,把漏网的脏数据补回来。这是轻易云客户常见的「增量 + 全量双轨」兜底模式——增量负责及时,全量负责兜底。

编码映射上,我们没有引入 _findCollection 或 _mongoQuery,所有仓库类型字段直接从源端透传过去。如果未来对账系统需要按仓库类型做业务分组,再加一个集中管理的编码映射集合即可,这种「编码映射集中管理」也是轻易云客户里很常见的应对模式。

踩坑复盘

自增主键当业务主键用:MySQL 端用 id 自增,千万不能再用 id 做唯一键;真正的业务唯一键是 warehouse_code,跨系统对照用 source_Id。
增量起点写死成「很早的日期」:如果永远用固定日期,数据量大了之后接口分页会非常慢,也很容易踩吉客云接口的分页上限。稳妥做法是把 gmtModifiedStart 改成 {{LAST_SYNC_TIME|datetime}},记录每一次成功的同步时间戳。
status 字段推导写反:isDelete=1 或 isBlockup=1 时应该映射成 0(禁用),不是 1。常见错误是直接把源端的某个字段塞进去。
idCheck 没开:idCheck=true 是避免重复插入的最后一道闸,一旦关掉,网络抖动重试时就会塞进重复行,后面清理非常麻烦。
停用 / 删除的仓库也同步进来:建议在源端过滤层就把 isDelete=1 的剔除,isBlockup=1 的按业务决定是否同步——别把它们都当启用状态写进去。

适用场景与不适用场景

适用:源端是吉客云(或同类 ERP)、目标端是 MySQL 的对账 / 报表系统,需要把仓库、供应商等基础资料做主数据同步,频率在分钟级,且不涉及复杂的字段计算。不适用:实时库存、交易流水这类对时效和事务一致性要求更高的场景,以及需要在目标端做复杂业务校验、对账规则的场景。