场景概览
适用场景
| 场景 | 痛点 | JSONMap/ValUtil 价值 |
|---|---|---|
| API 响应解析 | 多层嵌套取值繁琐 | 路径穿透，一行取值 |
| 动态表单/配置 | 字段不固定，无法定义 Bean | JSONMap 直接读写 |
| 前后端数据交互 | 类型不一致 | 自动类型转换 |
| 数据库 JSON 字段 | MySQL JSON 字段解析 | 直接操作和转换 |
| 第三方 API 对接 | 返回结构复杂，只需部分字段 | 精准提取，无需 DTO |
四大核心场景
1. 对接第三方 API
微信支付、支付宝等开放平台返回的 JSON 结构深、字段多。JSONMap 可以直接穿透取值：
JSONMap res = new JSONMap(response);
int status = res.getInt("data.pay_status");
String orderNo = res.getStr("data.order_info.transaction_id");
免去定义大量一次性 DTO。
2. 处理动态表单/配置
CMS、低代码平台中用户自定义字段不固定，通常以 JSON 存储在数据库的一个字段中：
JSONMap config = new JSONMap(dbUser.getConfigJson());
boolean darkMode = config.getBoolean("theme.dark_mode", false);
int maxUpload = config.getInt("limits.upload_size", 1024);
config.set("last_login.ip", "127.0.0.1");
3. 数据清洗与 ETL
服务间或新老系统迁移时，需要将一种 JSON 结构转换为另一种：
JSONMap target = new JSONMap();
target.set("userInfo.name", source.getStr("YHM"));
target.set("userInfo.status", source.getInt("ZT") == 1 ? "ACTIVE" : "LOCKED");
4. 快速原型开发
配合 DLZ-DB，Controller 层直接接收 JSONMap：
@PostMapping("/save")
public Result save(@RequestBody JSONMap params) {
DB.Table.insert("sys_user").addMap(params).execute();
return Result.ok();
}
与序列化框架的关系
| 工具 | 定位 | 擅长 |
|---|---|---|
| Jackson | 序列化框架 | JSON <-> Bean 转换 |
| FastJSON | 序列化框架 | 高性能转换 |
| JSONPath | 路径查询 | 复杂查询语法 |
| JSONMap | 数据操作 | 读+写+转换一体 |
JSONMap/ValUtil 解决的是"拿到数据后如何操作"的问题，与 Jackson/FastJSON 等序列化框架互补，而非替代。