轻易云自定义数据加工厂:五类钩子模板与实战指南
功能概览
我们设计这个功能的初衷是:在标准化的数据集成链路之外,为业务侧保留一段可编程、可热插拔的扩展空间。轻易云数据集成平台(DataHub)在每一次数据流转的关键节点都暴露了"加工厂"钩子,开发者只需编写一个轻量 PHP 类,即可对响应数据或请求参数进行改写、拆分、追加或回写。
平台目前内置五类钩子,覆盖数据从源到目标的全过程:
- BeforeSourceJobInsert:源平台接口调用前,用于在请求参数落地前做预处理。
- AfterSourceInvoke:源平台接口响应返回后,用于对原始响应做清洗、归并与字段重整。
- AfterTargetGenerate:目标队列生成后,用于在写入目标请求参数时补充汇总字段。
- BeforeTargetInvoke:目标平台接口调用前,用于触发反审核、附加动作或日志埋点。
- AfterTargetInvoke:目标平台接口响应返回后,用于把回执 ID 等信息回写到原队列文档。
每个钩子都以"构造函数 + run()"的固定形态暴露,响应或请求以引用方式传入,改写即生效,无需重启服务。
使用场景
典型使用场景是:标准映射无法满足业务规则的字段补充或状态联动。举几个我们常见的真实诉求:
- 运费转分录:源端出库单含
post_fee运费字段,但目标 ERP 不识别游离字段,需要在出库单体内追加一行规格码为2222、数量为 1、单价为运费金额的分录,BeforeSourceJobInsert是最合适的钩子。 - 组装单拆分:源端组装单的明细
stockAssembleDetailsDto同时包含成品与原料,业务上希望拆成product与material两个数组,这种归并逻辑适合放在AfterSourceInvoke。 - 订单实付金额汇总:目标队列在生成时只携带明细行,需要按
price * num汇总后写入paid字段,使用AfterTargetGenerate在入队前一次性算清。 - 推单前反审核:部分 ERP 平台要求推单前先调用反审核接口,以避免单据被占用;
BeforeTargetInvoke可在主推单前通过适配器 SDK 触发前置动作。 - 回执 ID 回写:目标平台返回
result后,需要把回执编号写回队列原始文档,便于后续对账,AfterTargetInvoke通过DataStorage完成 update。
配置说明
加工厂以独立 PHP 类文件形式部署在平台约定的扩展目录,文件命名必须与类名严格一致。开发者上传后,在对应集成策略的"加工厂"面板中按生命周期阶段挂载即可。
一个标准的加工厂模板包含三个要素:
- 构造函数:接收引用参数(
&$response或&$request)、适配器实例$adapter,部分钩子还会注入$job(队列任务对象)或$ids(mongodb objectId 列表)。引用传递是设计关键——加工厂内对数组的修改会直接反映到上下游。 - run() 方法:加工厂的执行入口,平台在调度到对应阶段时自动调用。
- 早退机制:在 run() 开头通常会用
if ($response['code'] != 200)或类似判断先做响应合法性校验,失败直接return,避免污染数据。
以 BeforeSourceJobInsert 为例,模板会遍历源响应中的单据数组,按业务条件向 details_list 追加分录;AfterSourceInvoke 则利用 &$response 的引用特性,对 result.data 的每一项重塑结构。BeforeTargetInvoke 还可以通过 $this->adapter->SDK->invoke(...) 调用目标平台的其他动作接口,通过 $this->adapter->getLogStorage()->insertOne(...) 落日志,方便排错。
挂载完成后,平台会在每次任务执行到对应阶段时自动实例化类、传入参数并执行 run(),无需人工干预。
注意事项
- 引用语义必须保留:构造函数里的参数全部使用
&引用传递,加工厂内的修改才会回写到底层数组。漏写引用符号将导致加工结果不生效。 - 类名与文件名一致:平台通过类自动加载机制加载加工厂,文件名需与类名严格匹配,否则会抛 Class Not Found 异常。
- 避免耗时操作:run() 在调度线程内同步执行,若在其中发起外部 HTTP 请求或长时间阻塞,将拖慢整个集成链路。必要时建议把耗时动作放到独立队列。
- 失败早退,避免脏数据:每个 run() 开头都应校验响应码或 success 标志,失败直接返回,不要继续遍历未通过校验的数据。
- 回写操作务必定位准确:
AfterTargetInvoke中通过_id回写时,务必使用$this->job->ids[0]等任务关联的 ID,不要硬编码,以免误更新其他单据。 - 日志与可观测性:复杂加工厂推荐通过
$adapter->getLogStorage()落关键节点日志,便于后续审计与排障。 - PHP 版本兼容:加工厂运行在平台托管的 PHP 运行时中,请避免使用宿主环境未启用的扩展函数。
通过自定义数据加工厂,业务团队可以把那些"标准映射表装不下"的逻辑下沉到平台原生钩子,既保留了轻易云数据集成平台(DataHub)主链路的稳定性,又获得了与自研脚本相当的灵活度。