JSONMap — Java 嵌套数据操作，一行到位

// 以前：10 行判空 + 强转，还可能 NPE
// 现在：1 行，没有中间对象，不会 NPE
String city = new JSONMap(response).getStr("data.user.profile.addresses[0].city");

<dependency>
    <groupId>top.dlzio</groupId>
    <artifactId>dlz-kit</artifactId>
    <version>6.6.4</version>
</dependency>

---

30 秒上手

// 解析 JSON
JSONMap data = new JSONMap("{\"user\":{\"name\":\"张三\",\"age\":\"25\"}}");

// 深层取值——路径不存在返回 null，不会 NPE
String name = data.getStr("user.name");          // "张三"
Integer age = data.getInt("user.age");            // 25（自动从字符串转）
List<Integer> ids = data.getList("user.ids", Integer.class); // 空返回空列表

// 构建嵌套结构——中间层级自动创建
JSONMap result = new JSONMap()
    .set("meta.version", "1.0")
    .set("data.user.name", "张三");
// → {"meta":{"version":"1.0"},"data":{"user":{"name":"张三"}}}

---

三个核心能力

深层路径取值

不用中间变量、不用逐层判空、不担心 NPE。

// 任意层级为 null → 返回 null
String v = data.getStr("a.b.c.d.e.f");  // null，没有异常

// 支持数组索引和负索引
String last = data.getStr("tags[-1]");  // 倒数第一个
Long time = data.getLong("history.logs[-2].timestamp");

// 类型自动转换
BigDecimal amount = data.getBigDecimal("order.payment.total");  // "99.9" → 99.9

动态结构构建

// 对比：传统方式需要逐层 new HashMap
// JSONMap：路径即结构
JSONMap req = new JSONMap()
    .set("header.traceId", UUID.randomUUID().toString())
    .set("header.source", "API")
    .set("body.user.name", "张三")
    .set("body.user.profile.city", "上海");

类型转换（ValUtil）

数据来源（前端表单、数据库、第三方 API）的类型不可控时，不用到处 try-catch。

Integer age = ValUtil.toInt(params.get("age"));              // 不抛异常，返回 null 或正确值
Integer safe = ValUtil.toInt(params.get("age"), 0);          // 带默认值
List<Integer> ids = ValUtil.toList(params.get("ids"), Integer.class); // "1,2,3" → [1,2,3]

---

不是替代 Jackson，是 Jackson 之后的那层

层	做的事	工具
序列化层	JSON 字符串 ↔ Java 对象	Jackson / Gson
操作层	拿到对象后怎么读写、构建、转换	JSONMap / ValUtil

Jackson 负责搬运，JSONMap 负责加工。两者互补，不冲突。

---

AI 辅助开发

JSONMap 的 API 模式固定、参数少、无重载歧义，AI 模型容易生成正确代码。

// AI 生成结果示例（来自真实 prompt 测试）
JSONMap resp = new JSONMap(callbackBody);
String orderId = resp.getStr("data.order.orderId");
Integer amount = resp.getInt("data.order.amount");

在 Cursor / Copilot 中将 docs/AI-速读指南.md 添加到上下文即可。

---

20 年积累，不止是一个工具类

这套代码从 2006 年开始积累，经过上百个内部项目的验证。核心设计原则"有界宽容"——对结构缺失宽容，对数据错误不放过——来自三次生产事故的教训。它不是一个月写出来的 demo，是 20 年修修补补沉淀下来的实用工具集。

---

同类工具定位

库	擅长	和 JSONMap 的关系
Jackson	JSON ↔ 对象	互补。Jackson 负责序列化，JSONMap 负责操作
JSONPath	查询语法	只读不写。JSONMap 能读能写能转 Bean
Hutool	全功能工具集	定位不同。JSONMap 更聚焦动态数据和嵌套操作

---

项目状态

• JDK：8 / 11 / 17 / 21
• 依赖：jackson-databind（你的项目大概率已有）
• 体积：~100KB
• 测试：完整测试用例覆盖

文档

• 快速上手
• JSONMap 完整指南
• ValUtil 类型转换
• @SetValue 注解映射
• 有界宽容原则
• 性能测试报告
• AI 速读指南（给 AI 模型看的快速参考）

---

如果觉得有用，点个 ⭐ 让更多人看到。