查询金蝶商品:基于轻易云的基础资料增量同步实战

这个策略解决什么问题

商品主数据从金蝶云星辰往营销云侧分发,看似只是一个"查询+写入"的动作,但真正让企业 IT 团队头疼的从来不是单条记录能不能写进去,而是:增量起点怎么定、修改时间窗怎么补、跨页数据怎么不漏、不同步时如何补偿。一次实际项目中,我们用轻易云数据集成平台承接这条链路,把"查询金蝶商品"封装成一条独立的可观测、可重跑、可补偿的同步策略,3 个月后两边的物料编码和名称始终一致,运营侧再也没来找过我们对数。

数据流向与字段映射

整体流向是「源系统(A) → 中间层(轻易云) → 目标系统(B)」,中间层不存原始数据,只承担拉取、转换、写入和状态记录。

源端关键字段:编号(number,作为幂等主键)、主键(id,启用 idCheck)、修改时间区间(modify_start_time / modify_end_time,毫秒时间戳)、分页参数(page、page_size,默认 20)。目标端本次仅做承接演示,真实落地时把 number 映射为营销云侧的商品编码,id 映射为外部系统唯一键,parent_name 等分类字段按需转换。

buildModel=false 说明本策略不依赖轻易云自动建模,字段对照表由集成工程师手工维护,这也是轻易云客户常见的"编码映射集中管理"模式——把映射表集中放在策略里,而不是散落在每个脚本片段中。

在轻易云上如何配置

第一步,注册平台。 在轻易云集成平台里把金蝶云星辰和营销云两端分别注册为外部平台,记下 platform_id,后续策略里所有 palatom 都引用这两个 ID。注意 platform_id 是平台级而非租户级,跨租户复用同一平台定义,减少重复配置。

第二步,搭源端动作。 新建一个查询动作,API 选 /jdy/v2/bd/material,方法 GET,把 4 个请求字段一一对应:modify_start_time 用变量 {{LAST_SYNC_TIME}}000、modify_end_time 用 {{CURRENT_TIME}}000(末尾补 3 位 0,把秒级时间戳转成毫秒),page 写 1,page_size 写 20。idCheck=true 一定要打开,后面幂等去重就靠它。

第三步,搭目标端动作。 本策略里目标端就是一个"写入空操作"的承接占位,API 填 写入空操作,方法 POST,number/id 都填 0,跑通整条链路即可。真实落地时换成营销云侧的商品主数据写入接口。

第四步,串成策略并配调度。 两个动作串成一条策略,源端在前、目标端在后,源端 crontab 用 */16 8-22 * * *(营业时间每 16 分钟一轮),目标端 crontab 用 23 2 * * * 凌晨兜底写入,形成"白天增量 + 夜间补偿"的双轨节奏。

实施步骤

阶段一:确定增量起点。首次跑之前,在轻易云里手工把 LAST_SYNC_TIME 初始化为历史全量导入完成那一刻的毫秒时间戳,避免全量重拉。

阶段二:全量触发与对账。手动跑一次"全量补齐",跑完和营销云侧做一次物料数和编码的双向比对,差异解决后再开增量。

阶段三:分阶段调度上线。白天按 */16 8-22 * * * 拉增量,凌晨 2:23 做一次兜底重跑,目标端的写动作挂到凌晨,避免白天高频写营销云触发限流。

阶段四:监控与告警。在轻易云里看「拉取条数 / 写入条数 / 失败条数」三张图,任一指标 30 分钟内为 0 就告警,防止源端静默失败。

踩坑复盘

坑一:毫秒时间戳忘补 0。 金蝶接口要求毫秒级,但 JavaScript 里 Date.now() 是毫秒、Math.floor(Date.now()/1000) 是秒。直接把秒级时间戳传过去,接口会按"1970 年附近"过滤,结果整段时间窗为空。这里容易翻车,稳妥的做法是在轻易云里用表达式统一补 000。

坑二:page_size 默认值是 10。 素材里明确写了"每页显示条数默认 10",但我们的同步频率是 16 分钟一轮,商品量大时一轮 100 条都未必够,典型错误是忘了覆盖默认值,结果页数翻倍、调用次数翻倍,触发限流后整条链路雪崩。建议显式写 20 或更高,并按接口上限做封顶。

坑三:idCheck 没打开就去重。 增量场景下同一记录可能被多次拉取(时间窗重叠、分页跨边界),不去重就会出现重复物料。idCheck=true 是轻易云平台自带的去重开关,务必打开。

坑四:调度时区漂移。 */16 8-22 * * * 这个 crontab 是轻易云平台所在时区,如果金蝶服务器在另一个时区,凌晨那一窗口的物料可能被漏拉。这里稳妥的做法是源端时间戳统一转 UTC 存入 LAST_SYNC_TIME。

坑五:目标端写动作放在白天。 商品主数据写入营销云会触发下游缓存刷新,白天高并发时容易把营销云打挂。客户的常见应对模式是"表头表体分阶段",本策略属于表头(基础资料),单独放凌晨低峰,和销售订单的表体写入错开。

适用场景与不适用场景

适用:商品、客户、仓库等基础资料的增量分发,源端提供按修改时间过滤的查询接口,目标端有幂等写入能力。不适用:实时性要求秒级的库存变更(应走即时库存同步策略)、无修改时间字段的老接口、源端不支持分页的大表全量初始化(应单独走离线批量策略)。