param-convert

基于映射规则的 JSON 参数转换：配置一组 ParamMapping 规则，把源 JSON 转换为目标 JSON。支持字段映射、8 种类型转换、[S] 动态数组占位符、Aviator 表达式计算与参数校验。

Java 8 · fastjson · Aviator · Maven 多模块

模块

模块	说明
param-convert-sdk	核心 SDK：ParamConvertUtil.mapFields(source, mappings, throwException)
param-convert-playground	配置演练场：网页上配置映射规则，实时查看 SDK 转换效果

适用场景

核心价值：报文结构差异用配置化的映射规则消化，而不是为每种格式硬编码一个适配器。新增一种格式 = 新增一组规则（可存库、可热更新），无需改代码发版。

• 多渠道 API 对接：同一业务对接多个第三方渠道（支付、物流、短信、渠道商），各家出入参报文结构、字段名、类型各不相同 —— 每个渠道一份映射配置，统一收敛到内部标准模型
• 回调报文归一化：各渠道异步回调/Webhook 格式五花八门，按渠道配置规则统一转成内部标准事件，rule 表达式顺带完成关键字段校验
• 开放平台 / API 网关参数适配：统一入参按目标服务的报文要求做字段映射、类型转换后再路由下发
• 流程编排 / 低代码平台节点传参：上游节点输出映射为下游节点入参（[S] 动态数组适合批量单据类节点），映射规则由平台界面配置而非写死
• 系统迁移与新旧接口兼容：新旧系统并行期间，旧报文按规则转新报文，兼容层不侵入业务代码，迁移完成后直接下线配置
• 轻量数据清洗：MQ 消息、导入数据的字段重命名、类型规整、表达式加工（如金额单位换算 amount / 100），不必为小需求引入 ETL 组件

效果展示

动态数组映射：源数组 other.order[S] 逐元素映射到目标数组，user.name 广播到每个元素

校验规则：user.age >= 18 不通过时错误收集进 errorMsg，其余规则继续执行

快速开始

# 构建全部模块并跑测试
mvn clean install

# 启动演练场，浏览器打开 http://localhost:8686
cd param-convert-playground && mvn compile exec:java

一个例子

JSONObject source = JSON.parseObject(
        "{\"other\": {\"order\": [{\"orderNo\": \"1001\"}, {\"orderNo\": \"1002\"}]}}");

List<ParamMapping> mappings = Collections.singletonList(
        new ParamMapping("#other.order[S].orderNo", "s1.order3[S].other.order1", "String"));

ParamConvertResultBO result = ParamConvertUtil.mapFields(source, mappings, true);
// result.getTarget():
// {"s1":{"order3":[{"other":{"order1":"1001"}},{"other":{"order1":"1002"}}]}}

更多用法见 param-convert-sdk/README.md。