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

元信息

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

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：

properties 复制代码

service.name=PlatformHttp
service.version=3.0.0

主路由请求入口：

xml 复制代码

<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 提取、下游转发准备与响应回写

核心路由片段如下：

xml 复制代码

<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：主订单转换接口

bash 复制代码

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

预期响应：

json 复制代码

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

API 2：JSONPath 内联响应示例

bash 复制代码

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

预期响应：

json 复制代码

{"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 网关场景，后续可继续扩展鉴权、参数校验、异常处理与真正的下游转发策略。