LightESB PlatformHttp v1.0.0：DS 数据转换实践基于 PlatformHttp v1.0.0

元信息

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

PlatformHttp v1.0.0 提供了一条可直接复用的 DS 数据转换路由：
在请求入口接收复杂订单 JSON，通过 conditionaltransform 按配置执行转换，并将转换后的结果直接响应回写。

背景与目标

在集成场景里，上游报文通常层级深、字段多，下游直接消费成本高。

这条路由聚焦四个目标：

建立清晰的 HTTP Listener 请求入口
将多层订单 JSON 扁平化为业务字段
为下游转发预留可复用的数据结构
保持响应回写稳定，降低编码问题风险

路由与配置说明

1) HTTP Listener 请求入口

来自 complex-json-transform-route.xml：

<from uri="undertow:http://0.0.0.0:{{server.port}}/api/transform/complex-order?httpMethodRestrict=POST" />

来自 common.config.properties：

server.port=18081
HTTP.Listener=true
system.components=undertowhttp,streamcache,jsontransform,conditionaltransform

最终请求地址：

POST http://localhost:18081/api/transform/complex-order

2) 条件化转换开关

路由调用：

<to uri="conditionaltransform:input?skipOnError=true"/>

转换相关配置：

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

含义：

input-transform=true 时执行输入转换
转换脚本使用 input-transform-with-import.ds
当转换异常且 skipOnError=true 时，流程不中断

3) DS 脚本与公共函数导入

主脚本：

lightesb-camel-app/PlatformHttp/v1.0.0/input-transform-with-import.ds

公共函数库：

lightesb-camel-app/TransformDS/common-functions.ds

脚本通过 import 复用通用逻辑：

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

典型映射能力：

通过 lib.formatFullName(...) 组装客户姓名
通过 lib.formatAddress(...) 组装地址
通过 lib.calculateLineTotal(...) 计算商品行总价
通过 lib.formatAmount(...) 统一金额格式

4) 响应回写

路由末尾包含：

<process ref="jsonResponseProcessor"/>

该处理器用于增强 JSON 响应回写时的 UTF-8 与格式稳定性。

请求与响应示例

请求示例

在仓库根目录执行：

curl -X POST "http://localhost:18081/api/transform/complex-order" \
  -H "Content-Type: application/json" \
  --data-binary "@lightesb-camel-app/PlatformHttp/v1.0.0/test.json"

响应示例（关键字段）

成功时可看到类似结构：

{
  "orderId": "ORD-2024-003",
  "customerName": "张明华",
  "items": [
    {
      "productId": "PROD-001",
      "lineTotal": 16198.2
    }
  ],
  "financial": {
    "currency": "CNY"
  }
}

可用 jq 快速校验关键结果：

curl -s -X POST "http://localhost:18081/api/transform/complex-order" \
  -H "Content-Type: application/json" \
  --data-binary "@lightesb-camel-app/PlatformHttp/v1.0.0/test.json" | jq '{orderId, customerName, itemCount: (.items|length), currency: .financial.currency}'

常见问题与排查

1) 端口不可访问

按顺序检查：

HTTP.Listener=true
server.port=18081
端口 18081 未被占用

2) 请求方法被拒绝

入口设置了 httpMethodRestrict=POST，调用必须使用 POST。

3) 未发生转换

检查：

input-transform=true
input-transform.file=input-transform-with-import.ds
DS 脚本路径和语法是否有效

4) import 文件找不到

input-transform-with-import.ds 依赖：

lightesb-camel-app/TransformDS/common-functions.ds

需确认文件存在，并且运行时路径解析正确。

总结

PlatformHttp v1.0.0 给出了一套稳定的 DS 转换基线：

明确的 HTTP Listener 请求入口
配置驱动的 conditionaltransform 转换控制
可复用的 DS 公共函数库
通过 jsonResponseProcessor 保证响应回写一致性

该模式适用于复杂 JSON 转换场景，后续可继续扩展参数校验、鉴权策略与下游转发策略。

LightESB PlatformHttp v1.0.0：DS 数据转换实践

元信息