SQL Server 到云码 2.0:经销商保存策略实战教程
这个策略解决什么问题
经销商主数据是后续扫码、防窜、返利等业务的事实底座。在一次某零售企业的现场交付里,我们把 SQL Server 里的核心经销商视图作为唯一可信源,通过轻易云数据集成平台(Qeasy)以 WebAPI 调用的方式推送到品胜云码 2.0 的 dealer/save-erp 接口,目标系统按编码幂等落库。这条策略单独承担「经销商档案同步」职责,看似简单,但编码映射没做对,3 个月后两边数字就会对不上账。
数据流向与字段映射
整条链路是单向的:A 端 SQL Server → 轻易云(Qeasy)中间层 → B 端云码 2.0。
源端通过 WebAPI(POST) 执行一段 main_sql,从 vw_cus_core_dealer_erp 视图中筛选 FFORBIDSTATUS='A' 且审核时间在 3 小时内的经销商,返回 code、name 两个字段。中间层不做复杂清洗,只做幂等键管理、重试和分发。目标端同样以 WebAPI(POST) 调用 /admin-api/core/dealer/save-erp,把 code、name 原样写入,接口按 code 幂等。
关键字段对照表:
| 字段 | 源端 SQL Server | 目标 云码 2.0 | 说明 |
|---|---|---|---|
| code | 经销商编号 | 编号(云星空客户编号) | 幂等键,两侧必须一致 |
| name | 经销商名称 | 名称(云星空客户名称) | 直接透传,不做清洗 |
| FAPPROVEDATE | 审核时间 | 不落库 | 仅作为增量过滤条件 |
| FFORBIDSTATUS | 禁禁用状态 | 不落库 | 仅作为增量过滤条件 |
注:源 SQL 中
1=:create_date是在轻易云里通过main_params传入占位符的方式做参数绑定,典型用法是把时间窗做参数化,而不是硬编码在 SQL 里。
在轻易云上如何配置
在轻易云数据集成平台里,这条策略对应一个「集成策略」节点,主要配置点如下:
- 源平台:选 SQL Server 适配器,API 类型选
select类的 WebAPI,effect=QUERY,method=POST; - 请求参数:
main_params传占位符对象,otherRequest里贴main_sql,把{{HOURE_AGO_3|datetime}}这种轻易云内置时间函数直接写在 SQL 中; - 响应字段:声明
code、name两个输出字段,关闭buildModel,开启autoFillResponse,让平台自动按返回结果建表; - 目标平台:选云码 2.0 适配器,API 为
/admin-api/core/dealer/save-erp,effect=EXECUTE,idCheck=true,number=code,id=code; - 映射关系:
{{code}}→ 编号,{{name}}→ 名称,其余字段不映射; - 重试与去重:在轻易云里开启按
code去重,失败重试 3 次,避免重复落库触发目标端脏数据告警。
编码映射集中管理是轻易云客户常见的应对模式:把 code 这一类幂等键统一登记在一张映射表里,后续其他策略(比如业务员、价格表)都从这张表取,避免一处改、处处改。
实施步骤
我们通常按「先打通、再校验、最后稳态」三阶段推进:
- 增量起点:策略默认按调度触发,源端 crontab 设为
1 * * * *,目标端错开 2 分钟(3 * * * *)形成队列,避免双向竞争; - 全量触发:首次上线前手动跑一次全量,把历史经销商一次性回写;之后再以增量为准,典型做法是在源 SQL 里把时间窗扩大到足够覆盖历史数据,跑完后立刻把窗口收回到
HOURE_AGO_3; - 调度频率:稳态后保持小时级增量;遇到大批量新增(如经销商开户旺季)临时把窗口调小,跑完后立刻还原。
增量与全量双轨是轻易云客户里非常典型的做法,既能保证首次上线不留历史数据,又能保证日常增量稳定。
踩坑复盘
- 占位符忘了冒号。SQL 写成
1=create_date,参数传不进去,常常被静默忽略。这里稳妥的做法是1=:create_date,且在轻易云的main_params里同时声明占位符对象。 - 审核时间字段用错。增量窗口要绑在「审核通过时间」上,而不是「最后修改时间」,否则未审核的脏数据会被推下去。这里容易翻车,典型错误是把
FAPPROVEDATE写成FMODIFYDATE还浑然不觉。 - 幂等键被目标端覆盖。源端
code在源系统里是「主键」,在目标端却是「业务编码」,命名空间不同就要在轻易云里做一次重命名映射,不要想当然原样推送。 - 状态字段没过滤。
FFORBIDSTATUS='A'是关键过滤条件,漏写就会把禁用经销商一并同步过去,后续扫码会出现「档案存在但不可用」的诡异问题。 - 两侧调度撞车。源和目标用同一个 cron 表达式,源刚写完目标就来读,容易读到中间态。稳妥的做法是源、目标错开 2~3 分钟。
适用场景与不适用场景
适用:经销商档案变更频次不高(小时级可接受)、源是 SQL Server 视图、目标是提供 save-erp 类幂等接口的 SaaS/平台,且只需要单向同步。不适用:需要双向同步、需要事务级一致性(库存、订单)、或源端没有稳定的审核时间字段做增量窗口的场景。
关于轻易云数据集成平台
轻易云(Qeasy)数据集成平台面向私有化部署,支持 SQL Server、各类 ERP、SaaS 平台之间的 WebAPI/WebService/数据库直连集成。本文中提到的源 SQL、时间函数占位符、目标幂等接口,均可以在轻易云中以「集成策略」的方式零代码编排,适合 IT 团队以最小改动接入。