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

元信息

适用版本：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：

xml 复制代码

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

来自 common.config.properties：

properties 复制代码

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

最终请求地址：

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

2) 条件化转换开关

路由调用：

xml 复制代码

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

转换相关配置：

properties 复制代码

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 复用通用逻辑：

datasonnet 复制代码

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

典型映射能力：

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

4) 响应回写

路由末尾包含：

xml 复制代码

<process ref="jsonResponseProcessor"/>

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

请求与响应示例

请求示例

在仓库根目录执行：

bash 复制代码

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"

响应示例（关键字段）

成功时可看到类似结构：

json 复制代码

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

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

bash 复制代码

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 数据转换实践

元信息

背景与目标

路由与配置说明

1) HTTP Listener 请求入口

2) 条件化转换开关

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

4) 响应回写

请求与响应示例

请求示例

响应示例（关键字段）

常见问题与排查

1) 端口不可访问

2) 请求方法被拒绝

3) 未发生转换

4) import 文件找不到

总结

Links