查询旺店通货品档案:基于轻易云的增量同步策略实战
这个策略解决什么问题
货品档案是供应链集成的「地基」:下游所有单据、库存、成本都依赖它。在一次实际项目中,客户希望把旺店通里的货品档案按最后修改时间增量拉到金蝶云星空,用于统一后续的采购、销售与库存口径。看似简单的「拉一下货品」,真正落地时要回答三个问题——按什么时间窗拉、怎么分页、停在哪里不丢不重。
数据流向与字段映射
数据流向是单向的:旺店通·企业奇门 → 轻易云集成平台 → 金蝶云星空。其中「轻易云集成平台」既是中间缓存,也是调度与映射的执行点。
源端 wdt.goods.query 接口是查询型 WebAPI,请求体里 start_time 用 {{LAST_SYNC_TIME|datetime}} 占位,end_time 用 {{CURRENT_TIME|datetime}},分页由 page_size 控制。目标端 metadata 是「写入空操作」形态——这并不奇怪,原因是金蝶侧的真实写入由后续「货品写入」策略承接,本策略只负责把数据从源端搬到中间层并打好时间戳。
关键字段对照如下:
| 含义 | 源端字段(旺店通) | 中间层 | 目标端(金蝶) |
|---|---|---|---|
| 货品编号 | goods_no | goods_no | 由下游策略映射 |
| 增量起点 | start_time | LAST_SYNC_TIME | — |
| 增量终点 | end_time | CURRENT_TIME | — |
| 是否含已删除 | deleted | deleted_flag | — |
| 分页大小 | page_size | page_size | — |
编码映射建议集中放在轻易云的「映射中心」统一维护,避免每个策略各写一套。
在轻易云上如何配置
第一,接入与认证:在轻易云数据集成平台里新建源端连接,选择「旺店通·企业奇门」适配器,填入授权信息。轻易云对这类 ERP/电商后台一般提供开箱适配器,省掉自封装 HTTP 客户端的工作。
第二,元数据建模:把 wdt.goods.query 的 request 字段按 JSON 逐个登记,idCheck 打开,buildModel 关闭(查询类接口通常无需建模为单据),autoFillResponse 打开便于自动探测返回结构。
第三,变量绑定:start_time 用平台时间变量 {{LAST_SYNC_TIME|datetime}},end_time 用 {{CURRENT_TIME|datetime}}。这一步看似一行配置,实际是整个增量逻辑的灵魂——边界算错就会丢单或重单。
第四,目标端先打桩:本策略目标端是「写入空操作」,目的是让源端查询链路独立跑通、把数据落到中间层并打时间戳,再由下游策略消费。
第五,日志与告警:在轻易云里打开运行日志保留、失败重试与异常告警,货品档案量大时这是救命稻草。
实施步骤
我们通常把这类策略分三阶段上线:
- 增量起点初始化:上线前一次性把
LAST_SYNC_TIME设为某个历史时间点(例如三个月前),先跑一次全量回灌,把基础档案铺平。 - 全量触发:在轻易云里手工触发一次全量调度,确认目标侧数据完整对得上。轻易云客户的常见做法是「增量与全量双轨」:全量作为兜底,增量作为日常。
- 调度频率上线:把 crontab 调整为
0 */2 * * *,即每 2 小时滚动一次窗口。频次不要过密,避免与上游业务高峰期抢资源;也不宜太疏,否则下游写入时延过大。
上线后建议在前两周每天核对一次「本次窗口条数」「累计条数」「异常条数」三项指标。
踩坑复盘
- 典型错误:end_time 用了
NOW()而不是平台变量。直接NOW()在跨时区、跨节点时容易产生毫秒级偏差,导致同一批数据被两个窗口重复拉取。稳妥的做法是用轻易云的{{CURRENT_TIME|datetime}}统一取值。 - 这里容易翻车:分页与时间窗的耦合。如果分页中途报错,时间窗已经推进,下一轮会跳过这一段。建议在轻易云里开启失败重试 + 时间窗回退策略,而不是简单地把
LAST_SYNC_TIME直接前移到CURRENT_TIME。 - 典型错误:把「已删除」当噪声直接丢。旺店通的
deleted=1其实是「包含已删除」,在中间层最好保留deleted_flag,由下游金蝶侧决定是停用还是真删,否则三个月后两边数字对不上。 - 踩坑点:目标端「写入空操作」被误解。不少同事第一次看到这个 metadata 以为配错了,其实它是「表头表体分阶段」的一种典型模式——查询与写入解耦,便于复用。
- 踩坑点:crontab 与时间窗的语义不一致。
0 */2 * * *表示「整点触发」,但数据写入按窗口推进;如果上游某一批在窗口边界附近落库,要预留至少一个调度周期的冗余。
适用场景与不适用场景
适用:上游是按修改时间增量提供的查询接口(如旺店通、各类 ERP 档案接口),下游需要稳定、按时序的中间层数据。不适用:上游只能全量导出、且不支持分页;或下游要求强实时(秒级)一致性,此时应改用消息订阅或变更通知类方案。