基本单位信息同步:从 MySQL 到金蝶云星空的实战方案
这个策略解决什么问题
基本单位信息是物料、采购、库存、销售所有下游单据都会引用的基础字典。一次实际项目中,客户源端 MySQL 存了上千条 UOM 记录,目标端金蝶云星空需要按自己的单位体系落地。如果两边口径不齐,后续物料、采购订单都会出问题。本策略要做的事很朴素:把源端计量单位主数据按增量方式稳定地推到目标系统,让下游业务可以放心引用。
数据流向与字段映射
源系统是 MySQL,通过轻易云数据集成平台(Qeasy)的 WebAPI 执行器发起 POST 请求,执行一段带占位符的 SQL,按 last_update_date >= {{LAST_SYNC_TIME|datetime}} 做增量抽取,分页通过 limit :limit offset :offset 控制。请求参数 main_params 绑定分页值。
目标端是金蝶云星空,目标侧 metadata 标识为「写入空操作」,这是轻易云在做编码映射集中管理时常采用的过渡写法:先把数据落到中间表或缓存层,由下游真正的写入策略或手工脚本消费。这样做的好处是把"抽取"和"落地"解耦,后续调整金蝶字段时只改下游一处即可。
关键字段对照表(源 → 目标语义):
| 源字段(英文) | 源字段(中文) | 目标侧语义 | 说明 |
|---|---|---|---|
| uom_id | 单位ID | 单位主键 | 幂等键,作为目标端去重依据 |
| uom_type | 单位类型 | 单位类别 | 需做枚举映射 |
| uom_code | 金蝶单位 | 单位编码 | 目标端唯一标识 |
| primary_flag | 主单位标识 | 是否基本单位 | 布尔转金蝶 Y/N |
| conversion_value | 与主单位换算关系 | 换算率 | 数值字段,谨慎精度 |
| decimal_number | 小数位数 | 精度 | 整数映射 |
| process_mode | 尾数处理方式 | 舍入方式 | 枚举映射 |
| enable_flag | 是否有效 | 启用标志 | 决定目标端是否禁用 |
在轻易云上如何配置
源端在轻易云配置器里选 WebAPI → select,请求体绑定 main_params 与 main_sql,main_sql 内嵌 {{LAST_SYNC_TIME|datetime}} 占位符,平台每次执行前会自动替换为上一次同步成功的时间戳,这是轻易云做"增量与全量双轨"的常见做法。idCheck 置为 true,让平台按 单位ID 做幂等去重,避免重复写入。
目标端配置为「写入空操作」(number=0,id=0),即把上游结构化结果暂存,等待下游策略消费。如果客户环境特殊,也可以直接把目标端改为金蝶云星空的保存接口,实现一次性落地。
调度上源端 crontab 设为 */59 * * * *,即每 59 分钟一次。这个数字不是拍脑袋:单位主数据一天变不了几条,频次过高反而徒增日志;同时 59 分钟避开整点,把负载从整点高峰里挪出来。目标端 crontab 设为 */5 * * * *,高频小批地把缓存层数据推到目标系统。
实施步骤
第一阶段:增量起点确认。 第一次执行前,需要人工确认一个合理的 LAST_SYNC_TIME 起点。稳妥的做法是取源端 last_update_date 的历史最小值往前推一天,先做一次冷启动全量,再用 last_update_date >= {{LAST_SYNC_TIME}} 接续。
第二阶段:全量触发与对账。 通过轻易云的「全量触发」按钮跑一次,核对目标端条数与源端 SQL 结果条数是否一致。对账维度建议看三件事:总条数、空值比例、关键字段(单位编码、主单位标识)非空率。
第三阶段:调度频率上线。 全量对账通过后,把源端 */59 * * * *、目标端 */5 * * * * 两个调度同时开启,运行 24 小时观察日志。无异常后,把目标端从「写入空操作」切换为金蝶云星空的真实保存接口。
踩坑复盘
-
占位符没替换导致全表扫描。 典型错误是直接把
{{LAST_SYNC_TIME|datetime}}写成固定值,看似跑通,实则每次都拉全量。这里容易翻车,稳妥的做法是上线前先在轻易云执行历史里抽查一次 SQL 实际绑定值。 -
decimal_number与conversion_value的精度。 MySQL 这两个字段若定义为 float,跨库传输后会出现 0.1+0.2 那种尾差。建议在 SQL 里CAST(... AS DECIMAL(20,8))后再返回。 -
枚举映射忘了做。
uom_type、process_mode、enable_flag在金蝶云星空侧是枚举,直接写字符串会被目标端拒收。轻易云客户常见的应对模式是把枚举集中维护到一张映射表,源策略只引用键值,后续枚举调整只动映射表。 -
目标端「写入空操作」被当成完成态。 这是部署在私有化环境里很常见的一个误判:配置里看到 200 就以为同步成功了,其实只是落到了缓存层。一定要在监控视图里区分"抽取成功"和"落地成功"两个指标。
-
调度频次与源端写入高峰冲突。 把
*/59改成*/5看似更实时,但单位主数据写入本就稀疏,反而把轻易云的连接池和源端 binlog 翻得滚烫。一周后客户现场反映慢,回滚频次就恢复了。
适用场景与不适用场景
适用:单位、币别、税率、仓库等基础字典类主数据同步;变更稀疏、对幂等要求高、需要编码映射集中管理的场景。不适用:业务单据同步(应走带表头表体的分阶段策略)、高频事务类数据(分钟级以下变更)、需要复杂反写校验的库存事务。