# param-convert

**Repository Path**: ybkksd/param-convert

## Basic Information

- **Project Name**: param-convert
- **Description**: 基于映射规则的 JSON 参数转换 SDK（Java 8 + fastjson + Aviator），支持字段映射、类型转换、[S] 动态数组与表达式校验，附可视化配置演练场
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-05
- **Last Updated**: 2026-07-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java, JSON, Aviator, 强大的参数转换, 复杂规则映射

## README

# param-convert

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

Java 8 · fastjson · Aviator · Maven 多模块

## 模块

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

## 适用场景

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

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

## 效果展示

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

![动态数组目标路径](docs/images/preset-dynamicTarget.png)

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

![校验规则失败](docs/images/preset-validate.png)

## 快速开始

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

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

## 一个例子

```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](param-convert-sdk/README.md)。