查询聚水潭类目:一条「只查不写」的同步策略实战

这个策略解决什么问题

某零售企业的商品主数据分散在聚水潭和金蝶云星辰两侧,后续要做商品档案同步,第一步必须先把两边的「类目树」对齐。直接同步商品会踩两个坑:一是类目没建好就推商品,编码映射全是空的;二是两边类目命名规则不同,事后补救代价大。我们用轻易云做的第一件事,就是把聚水潭的类目按修改时间窗定时拉到平台中间层,做一次「只查不写」的盘点。

数据流向与字段映射

源是聚水潭的 /open/category/query 接口,目标是轻易云集成平台内部的写入空操作(用于触发调度并落中间表)。关键字段对照如下:

注意源接口要求修改时间窗与商品编码不能同时为空,我们用时间窗即可,不传商品编码。

在轻易云上如何配置

打开轻易云数据集成平台的策略编辑器,新建一个 QUERY_ONLY 类型策略,源选聚水潭,目标选 datahub(平台自身)。

配置要点有三个:

1. 元数据接入:直接引用素材里的 source/target 元数据 JSON,确认 effect=QUERY、method=POST、autoFillResponse=true。idCheck 保持 false,因为这是首次盘点,不依赖已存在记录。
2. 请求参数模板:page_index 默认 1,page_size 写死 50,modified_begin 和 modified_end 用平台内置时间宏 {{LAST_SYNC_TIME|datetime}} 和 {{CURRENT_TIME|datetime}}。轻易云的客户现场常见做法是把这两个宏单独提一行,不放进业务字段,便于排查时区漂移。
3. 响应落库:autoFillResponse 开启后,聚水潭返回的 c_id、c_name、modified 等字段会按同名规则写入中间表;不需要写自定义解析脚本。

实施步骤

分阶段推进,我们建议按「先验通、再定时、最后兜底」的节奏来:

• 阶段一:手工触发,验通链路。在轻易云策略详情页点「单次执行」,选一个已知有更新的时间窗(例如最近 24 小时),观察返回条数与中间表行数是否一致。这里最容易翻车的是时间格式——聚水潭要求 yyyy-MM-dd HH:mm:ss,传成 ISO 时间戳会被静默丢弃。
• 阶段二:配置增量起点。第一次全量拉取时,把 LAST_SYNC_TIME 设为聚水潭类目最早修改时间之前的某个值,确保一次拉干净;跑完之后,轻易云会自动记录本次 CURRENT_TIME 作为下次起点。
• 阶段三:接入调度。参考素材里的 crontab: */5 8-20 * * *,意思是每天 8 点到 20 点,每 5 分钟一轮。我们在实际项目里也看到客户把这条策略压到 30 分钟一次,因为类目变更频次远低于商品;稳妥的做法是先用较密频次跑一周,确认没有漏单再放宽。
• 阶段四:幂等与重试。聚水潭接口时间窗不能超过 7 天,且网络抖动偶有 502。轻易云的重试机制会自动续跑,但要确认 idCheck 在「写入空操作」目标里设了 true,避免重复触发写入。

踩坑复盘

1. 时间窗超过 7 天直接报错。聚水潭的硬限制,官方文档写得很清楚,但客户现场常因为调整服务器时区,把开始时间算成了 8 天前。建议在轻易云的时间宏里强制锁定时区为 Asia/Shanghai。
2. page_size 超过 50 被截断。素材里写「最大 50」,但有工程师误以为是「建议 50」,传了 200,接口静默只返 50 条,后续分页逻辑全乱。稳妥的做法是硬编码 50,不留口子。
3. 首次全量与增量混跑。如果第一次没把 LAST_SYNC_TIME 归零,轻易云会按增量起点开始拉,老数据永久漏掉。我们在交付清单里强制要求「首次执行必须人工指定起点时间」。
4. 类目名称含特殊字符。聚水潭类目名允许 &、/、（）,中间表如果用 UTF-8mb4 + 默认排序规则没问题,但下游金蝶云星辰那边历史编码只接受 ASCII,这一步只拉到中间层不做转换,把转换集中到写策略里统一处理。
5. 依赖策略的调度顺序。这条 A 序列策略是上游,后面 B 序列「查询金蝶商品分类列表」要等它跑完才能比对。我们用轻易云的 depends_on 字段显式声明依赖,避免两套类目同时在跑、互相覆盖中间表。

适用场景与不适用场景

适合两侧系统都需要商品主数据、但先要盘点类目/分类树是否一致的集成初期阶段。不适合类目实时变更(秒级)且下游强依赖的场景——5 分钟轮询粒度对这类需求偏粗,需要改用事件驱动或流式接口。