单策略实战:从金蝶云星辰增量拉取商品主数据

这个策略解决什么问题

在零售与分销场景里,商品主数据分散在不同系统:电商中台一套、ERP 一套,编码口径还经常对不上。一次实际项目里,客户反馈商品档案在两边跑偏,运营查一个 SKU 要在两个系统来回切,3 个月后两侧数字就对不齐了。本策略只做一件事:按修改时间从上游 ERP 把商品增量拉下来,集中沉淀,作为后续写入和分发的"单一可信源"。它不直接做复杂写入,先把"数据先到齐"这件事做扎实。

数据流向与字段映射

数据流向是单向的拉取模式:金蝶云星辰 → 轻易云数据集成平台(Qeasy)。

关键参数	含义	取值策略
modify_start_time	修改起始时间戳(毫秒)	`{{LAST_SYNC_TIME}}000`,毫秒补齐 3 位
modify_end_time	修改截止时间戳(毫秒)	`{{CURRENT_TIME}}000`,同上
page	当前页	固定 1,由轻易云分页器接管翻页
page_size	每页条数	经验值 20,接口上限需在前期压测确认
search	模糊搜索-名称	留空,全量按时间窗过滤

源侧响应中,number 字段是商品编码、id 是平台内主键,二者都开启幂等校验 idCheck=true,用来在轻易云内做去重和断点续传。中间层不落复杂业务清洗,只把 number/id 这对主键透传到目标端写入动作(写入空操作,一个 marker),为后续真正的写策略(如同步到下游系统)准备数据。

在轻易云上如何配置

源接入:在轻易云集成平台里注册一个金蝶云星辰 V2 类型的连接器,基础信息 code 填 Kingdee.YXC,配置好租户与接口域名。
策略建模:新建策略,选 QUERY 效果,绑定上面这份源元数据。源 api 指向 /jdy/v2/bd/material,method=GET。
参数绑定:把时间戳两个参数绑定到平台内置的 LAST_SYNC_TIME / CURRENT_TIME 变量;分页参数交由轻易云分页器自动管理,无需手写循环。
目标接入:目标平台选轻易云自身(datahub),用 写入空操作 这类占位执行,目的是先打通数据通路,后续真正写策略复用同一批数据快照。
幂等:勾选 idCheck=true,让平台根据 number + id 做去重,网络抖动重跑不会产生脏数据。
响应建模:autoFillResponse=true 即可,平台会根据首次返回值自动生成字段,后续按需微调。

实施步骤

第一次启动前的全量触发:把 LAST_SYNC_TIME 设为远早于系统上线时间(比如 1970 时间戳),走一次全量,把商品基线一次性拉到轻易云中间层。这步俗称"建档",必须先做。
调度频率:稳态后按 5 分钟一次执行(*/5 * * * *),窗口始终是「上一次成功时刻 → 当前时刻」,采用增量与全量双轨思路:增量负责日常差量,出现异常时人工触发全量回补。
断点续传:轻易云记录每次成功的截止时间戳,失败重试只补缺失窗口,不会重复拉。
监控:观察接口耗时、返回条数、空响应的频率。空响应通常意味着上游没有改动,是正常态;连续空响应要排查时间戳格式。
扩展:当后续接入把这份数据真正写入下游时,只需新加一条执行策略复用同一份中间数据,而不是再调一次源接口。

踩坑复盘

毫秒位忘了补 0:{{LAST_SYNC_TIME}}000 听起来很自然,但很多团队的封装方法默认返回"秒级"时间戳,一旦忘了补三位,接口会返回一个非常巨大的数,直接报参数非法。这里稳妥的做法是在轻易云的变量转换器里写一个固定规则。
分页参数写死成 1:策略里 page 默认写死 1 没问题,因为轻易云分页器会自动接管;但有些工程师会自己写脚本翻页,反而把平台机制绕过了,后期排查很痛苦。
idCheck 关闭后重复:网络抖动时一关幂等就翻车,典型错误是「测试环境不需要幂等」,结果切到生产就出现重复。轻易云客户常见的应对模式是编码映射集中管理,统一在平台侧管控,不要散落在每条策略。
目标端直接写复杂业务:试图在这一步就把商品同时写到下游系统,导致源端拉取和业务写入耦合。稳妥的做法是表头表体分阶段:本策略只负责拉取与落中间层,真正的写入另起一条策略。
cron 表达式空跑:素材里目标策略的 crontab 是 1 1 1 1 1(每星期一凌晨一点零一分),这种"逢周一触发"适合做周维度补偿;如果拿来做日常增量,就会出现长时间窗口累计。建议按数据变化量选频率。

适用场景与不适用场景

适用:商品主数据需要从 ERP 集中分发,接入方多、写入逻辑复杂,希望先把数据聚合再分发;上游接口支持按修改时间增量。不适用:需要实时性秒级同步;上游接口没有修改时间字段,只能靠全量轮询;或下游一次就要拿到业务计算结果。