LightESB PlatformHttp v2.0.0：基于 SPI 与 DataSonnet 的 DTS 转换实践

TL;DR

PlatformHttp@v2.0.0 对外提供统一 HTTP Listener 请求入口：POST /2.0.0/api/demo。
路由通过 invokeDtsTransform(...) 在一次请求中串联多个转换能力。
第三方转换实现通过 Java SPI 从 services/TransformDS 动态加载。
输入转换脚本可继续通过 DataSonnet import 复用公共函数，降低规则重复。

元信息

适用版本：PlatformHttp@v2.0.0
关联服务：PlatformHttp@v2.0.0@complex-json-transform-route.xml

背景与目标

在真实集成项目中，常见诉求通常同时存在：

路由层需要编排多个业务转换结果
运行时需要可插拔扩展，且不改 LightESB 核心源码

PlatformHttp v2.0.0 给出一条清晰路径：

保持稳定的 HTTP Listener 请求入口
使用统一转换调用入口 invokeDtsTransform
从 services/TransformDS 装载第三方转换扩展
用 DataSonnet 公共函数库维持脚本可维护性

路由与配置说明

1) HTTP Listener 请求入口

来自 lightesb-camel-app/PlatformHttp/v2.0.0/complex-json-transform-route.xml：

<from uri="undertow:http://0.0.0.0:{{server.port}}/{{service.version}}/api/demo" />

来自 lightesb-camel-app/PlatformHttp/v2.0.0/common.config.properties：

server.port=18081
HTTP.Listener=true

来自 lightesb-camel-app/PlatformHttp/v2.0.0/service.config.properties：

service.version=2.0.0

最终可调用入口：

POST http://localhost:18081/2.0.0/api/demo

2) 路由中的 DTS 统一调用

该路由连续调用：

<method ref="commonFunctions" method="invokeDtsTransform('transformComplexOrder', ${body})" />
<method ref="commonFunctions" method="invokeDtsTransform('transformOrderSummary', ${body})" />
<method ref="commonFunctions" method="invokeDtsTransform('transformCustomerSnapshot', ${body})" />
<method ref="commonFunctions" method="invokeDtsTransform('transformRiskTags', ${body})" />

收益很直接：

一次请求可产出多个转换结果
路由代码不依赖具体 Provider 类名，扩展替换成本低

3) SPI 装载模型与投放位置

结合 docs/23-third-party-dts-extension-guide.md 与 services/TransformDS/README.md，运行链路为：

扫描目录 services/TransformDS
匹配并加载 *.jar
通过 ServiceLoader<LightesbDtsExtension> 发现扩展
按 supportedTransforms() 建立 transformName -> provider 映射
同名冲突时按 priority() 选高优先级

运维层面的含义：

扩展 Jar 投放到 services/TransformDS 即可生效
路由仍保持 invokeDtsTransform('<transformName>', ...) 统一调用
常规扩展发布不需要改 LightESB 核心代码

4) DataSonnet import 复用公共规则

来自 lightesb-camel-app/PlatformHttp/v2.0.0/input-transform-with-import.ds：

local lib = import 'lightesb-camel-app/TransformDS/common-functions.ds';

来自 lightesb-camel-app/PlatformHttp/v2.0.0/common.config.properties：

input-transform=true
input-transform.file=input-transform-with-import.ds

这样可以把格式化、拼接、计算等通用逻辑集中管理，主脚本只保留业务映射意图。

请求与响应示例

请求示例

在仓库根目录执行：

curl -X POST "http://localhost:18081/2.0.0/api/demo" \
  -H "Content-Type: application/json" \
  --data-binary "@lightesb-camel-app/PlatformHttp/v2.0.0/test.json"

响应示例（结构）

该路由最终组装的响应结构为：

{
  "complexOrder": "{...}",
  "orderSummary": "{...}",
  "customerSnapshot": "{...}",
  "riskTags": "{...}",
  "formattedAmount": "",
  "validatedField": ""
}

快速核验命令：

curl -s -X POST "http://localhost:18081/2.0.0/api/demo" \
  -H "Content-Type: application/json" \
  --data-binary "@lightesb-camel-app/PlatformHttp/v2.0.0/test.json" | jq '{complexOrder, orderSummary, customerSnapshot, riskTags}'

常见问题与排查

1) 报错 No DTS extension found

优先检查：

transformName 与 supportedTransforms() 是否完全一致
扩展 Jar 是否在 services/TransformDS
SPI 描述文件路径与实现类全限定名是否正确

2) 同名转换冲突

多个 Provider 声明同一 transformName 时，运行时按 priority() 选择高优先级实现。

3) 接口无法访问

检查：

HTTP.Listener=true
server.port=18081
请求路径包含版本段 /2.0.0/api/demo

4) DataSonnet import 解析失败

检查：

input-transform.file=input-transform-with-import.ds
被导入公共库路径是否符合当前运行时解析规则

总结

PlatformHttp v2.0.0 这套实现给出了面向生产的 DTS 组合方案：

HTTP Listener 保持稳定请求入口
invokeDtsTransform 提供统一的转换分发接口
SPI + services/TransformDS 支撑运行时可插拔扩展
DataSonnet import 提升转换脚本复用性与可维护性

当团队既要快速交付转换能力，又要保留扩展治理与灰度空间时，这个模式非常实用。