LightESB PlatformHttp v3.0.0：JSONPath 订单转换 HTTP 路由实战基于 Platf

元信息

适用版本：PlatformHttp@v3.0.0
关联服务：PlatformHttp@v3.0.0@platform-http-route.xml

PlatformHttp v3.0.0 给出了一套非常直接的请求处理模式：接收订单 JSON，请求入口完成 JSONPath 关键字段提取，再进行稳定的 JSON 响应回写。

本文基于仓库现有配置与路由，拆解这条路由的设计要点，并给出可直接验证的请求示例。

背景与目标

集成服务在对接上游系统时，通常要同时满足四个目标：

建立清晰、可控的 HTTP Listener 请求入口
尽早提取关键业务字段（如 orderId）
保持服务级日志可观测，方便快速排障
保证响应回写稳定，避免中文编码问题

PlatformHttp v3.0.0 的路由配置正是围绕这些目标展开。

路由与配置说明

1) 监听开关与端口配置

来自 common.config.properties：

server.port=18080
HTTP.Listener=true
system.components=undertowhttp

含义如下：

HTTP.Listener=true：启用 Undertow 监听能力
server.port=18080：服务对外监听端口
system.components=undertowhttp：启用 Undertow 相关组件能力

2) 服务版本与请求入口路径

来自 service.config.properties：

service.name=PlatformHttp
service.version=3.0.0

主路由请求入口：

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

最终请求地址为：

POST /3.0.0/transform/order

通过 {{service.version}} 注入版本号，可以让 URL 版本语义更清晰。

3) JSONPath 提取、下游转发准备与响应回写

核心路由片段如下：

<log message="orderId (JSONPath): ${jsonpath($.orderId)}"/>
<setProperty name="extractedOrderId"><jsonpath>$.orderId</jsonpath></setProperty>
<setHeader name="OrderId"><jsonpath>$.orderId</jsonpath></setHeader>
...
<transform><simple>{"status": "success", "message": "请求处理完成"}</simple></transform>
<process ref="jsonResponseProcessor"/>
<setHeader name="Content-Type"><constant>application/json</constant></setHeader>

设计价值：

请求入口可观测：servicelog 输出请求头和请求体，便于链路排查
下游转发预留：OrderId 同时写入 Property/Header，便于后续下游转发路由复用
响应回写稳定：jsonResponseProcessor 与 Content-Type 配置保证 JSON 输出一致性

请求与响应示例

API 1：主订单转换接口

curl -X POST "http://localhost:18080/3.0.0/transform/order" \
  -H "Content-Type: application/json" \
  -d "{\"orderId\":\"ORD-20260409-001\",\"amount\":299.50}"

预期响应：

{"status":"success","message":"请求处理完成"}

API 2：JSONPath 内联响应示例

curl -X POST "http://localhost:18080/3.0.0/transform/order1" \
  -H "Content-Type: application/json" \
  -d "{\"orderId\":\"ORD-20260409-002\"}"

预期响应：

{"status":"ORD-20260409-002","message":"请求处理完成"}

常见问题与排查

1) 端口不可访问

按顺序检查：

HTTP.Listener=true
server.port=18080
端口 18080 未被其他进程占用

2) 请求方法被拒绝（405）

路由入口配置了 httpMethodRestrict=POST
调用必须使用 POST

3) 路径或版本不匹配

路径包含 {{service.version}}
请求 URL 必须是 /3.0.0/transform/order 或 /3.0.0/transform/order1

4) 中文响应乱码或编码异常

保留 jsonResponseProcessor 处理器
确认响应头为 Content-Type: application/json

总结

PlatformHttp v3.0.0 提供了一个可直接复用的 HTTP 路由基线：

明确的 HTTP Listener 请求入口
早期 JSONPath 字段提取
面向排障的服务级日志
稳定一致的 JSON 响应回写

该模式适用于订单转换类 API 网关场景，后续可继续扩展鉴权、参数校验、异常处理与真正的下游转发策略。

LightESB PlatformHttp v3.0.0：JSONPath 订单转换 HTTP 路由实战

元信息