🗡️ JSONMap —— Java 数据操作的瑞士军刀

一行代码穿透复杂 JSON，告别 Java 数据处理的"体力活"

🤖 AI 时代的最佳拍档：让 AI 生成的代码减少 90% 冗余，节省 Token

// 以前要写 10 行的判空+强转，现在 1 行搞定
String city = json.getStr("user.profile.addresses[0].city");

---

⚡ 为什么选择 JSONMap？

特性	说明
🪶 极致轻量	仅 ~100KB，不给项目增加负担
🔗 唯一依赖	只依赖 jackson-databind（你的项目大概率已经有了）
🛡️ 0 侵入	不改任何现有代码，想用就用，不想用就删
☕ 全版本兼容	JDK 8 / 11 / 17 / 21 全部支持
🚀 即插即用	加一行依赖，2 分钟上手
😄 熟悉的味道	Ta就是你熟悉的HashMap，套了个马甲就身价百倍了
🤖 AI 友好	让 AI 生成的代码减少 90% 冗余，节省 Token
🏆 久经考验	20 年积累，上百个项目验证，稳定可靠

---

🚀 30 秒快速开始

1. 添加依赖

<dependency>
    <groupId>top.dlzio</groupId>
    <artifactId>dlz-comm</artifactId>
    <version>6.5.1</version>
</dependency>

2. 开始使用

// 就这样，没有任何配置，没有任何初始化
//yourJsonString: {"user":{"name":"张三","profile":{"addresses":[{"city":"上海"}]}}}";
JSONMap data = new JSONMap(yourJsonString);
String name = data.getStr("user.name");// → "张三"
String city = data.getStr("user.profile.addresses[0].city");// → "上海"

没错，就这么简单。

💥 3 秒感受降维打击

场景1：深层嵌套取值

❌ 传统 Java 方式

// 从 API 响应中获取用户的城市信息
Map<String, Object> response = getApiResponse();
String city = null;
if (response != null) {
    Object data = response.get("data");
    if (data instanceof Map) {
        Object user = ((Map) data).get("user");
        if (user instanceof Map) {
            Object profile = ((Map) user).get("profile");
            if (profile instanceof Map) {
                Object addresses = ((Map) profile).get("addresses");
                if (addresses instanceof List && !((List) addresses).isEmpty()) {
                    Object firstAddr = ((List) addresses).get(0);
                    if (firstAddr instanceof Map) {
                        city = (String) ((Map) firstAddr).get("city");
                    }
                }
            }
        }
    }
}

✅ JSONMap 方式

String city = new JSONMap(response).getStr("data.user.profile.addresses[0].city");

12 行 → 1 行，代码量减少 90%

---

场景2：动态构建复杂结构

❌ 传统方式：疯狂 new HashMap

// 需要返回给前端的结构
// {"meta":{"version":"1.0","timestamp":1234567890},"data":{"user":{"name":"张三"}},"errors":[]}

Map<String, Object> result = new HashMap<>();
Map<String, Object> meta = new HashMap<>();
meta.put("version", "1.0");
meta.put("timestamp", System.currentTimeMillis());
result.put("meta", meta);
Map<String, Object> data = new HashMap<>();
Map<String, Object> user = new HashMap<>();
user.put("name", "张三");
data.put("user", user);
result.put("data", data);
result.put("errors", new ArrayList<>());

✅ JSONMap：意念构建

JSONMap result = new JSONMap()
    .set("meta.version", "1.0")
    .set("meta.timestamp", System.currentTimeMillis())
    .set("data.user.name", "张三")
    .set("errors", new ArrayList<>());

10 行 → 4 行，代码量减少 60%

---

场景3：前端传参类型混乱

❌ 传统方式：各种 try-catch

// 前端传来的参数，类型永远是个谜
// {"age":"25","price":99.9,"count":"3.0","ids":"1,2,3"}

Integer age = Integer.parseInt(params.get("age").toString()); // 可能抛异常

✅ ValUtil：随便你传什么，我都能转

Integer age = ValUtil.toInt(params.get("age"));           // null 或 正确值
Integer age = ValUtil.toInt(params.get("age"), 0);        // 带默认值
List<Integer> ids = ValUtil.toList(params.get("ids"), Integer.class); // 自动拆分 "1,2,3"

容错性极强，永不抛异常

---

🛠️ 独创三大“神兵利器”

JSONMap 将复杂操作封装为三个核心能力，直击 Java 开发痛点。

1. 🎯 穿云箭：深层路径直达 (Deep Path Access)

独创亮点：无需任何中间对象，直接通过点号和下标穿透任意层级。

• 智能判空：路径中任意一环为 null，直接返回 null，绝无 NPE。
• 支持负索引：tags[-1] 直接获取数组倒数第一个元素（Python 风格）。
• 混合解析：完美处理 Map 中嵌套 List，List 中嵌套 Map 的复杂场景。

// 获取倒数第二个历史记录的时间戳
Long time = map.getLong("history.logs[-2].timestamp"); 

2. 🏗️ 这里的“独创”：意念构建 (Hierarchical Construction)

独创亮点：想构造 {"a":{"b":{"c":1}}}？别再 new 三个 HashMap 了！

• 自动铺路：只要你给路径，中间缺 Map 补 Map，缺 List 补 List。
• 智能合并：路径已存在？自动识别是“覆盖”还是“合并”。

// ✨ 魔法般的构建过程
JSONMap config = new JSONMap()
    .set("server.port", 8080)             // 自动创建 server 对象
    .set("db.master.ip", "192.168.1.1")   // 自动创建 db 和 master 对象
    .add("users", "admin") ;      // 自动创建 users 数组
// 结果：{"server":{"port":8080},"db":{"master":{"ip":"192.168.1.1"}},"users":["admin"]}

3. 🧬 变形金刚：全能类型转换 (Universal Type Casting)

独创亮点：源数据是什么类型不重要，重要的是你想要什么类型。

• 容错性极强：数据库存的是 String "100"，代码想要 int 100？自动转。
• 对象映射：想把某个子节点直接转成 Java Bean？一键搞定。

// 源数据：{"score": "99.5", "info": {...}}
BigDecimal score = map.getBigDecimal("score"); // 自动解析字符串为数字
User user = map.getObj("info", User.class);     // 子节点直接转对象

---

🔄 Bean 无缝互转

不是替代 Bean，而是增强 Bean！

// Bean → JSONMap（需要临时加字段？没问题）
User user = getUser();
JSONMap data = new JSONMap(user)
    .set("extra.loginTime", System.currentTimeMillis())
    .set("extra.source", "API");
// JSONMap → Bean（前端传的类型乱七八糟？自动纠正）
JSONMap params = new JSONMap(request.getBody());
// 即使前端传 {"age": "25"}（字符串），也能正确转成 Integer
User user = params.as(User.class);

---

📦 工具三剑客

工具	用途	一句话介绍
JSONMap	Map 增强	深层取值 + 链式构建 + 类型转换
JSONList	List 增强	支持负索引 + 类型安全访问
ValUtil	类型转换	万能转换器，空值安全

---

🆚 和主流库的定位差异

库	定位	擅长	JSONMap 的差异
Jackson	序列化	JSON ↔ 字符串	JSONMap 解决的是拿到数据后怎么操作
FastJSON	序列化	高性能	深层取值仍需链式 .getJSONObject().get()
JSONPath	查询	复杂查询语法	JSONMap 能读也能写，还能转 Bean
Hutool JSONUtil	工具集	功能全	JSONMap 更聚焦，体积更小

Jackson 负责"搬运"，JSONMap 负责"加工"，完美互补。

---

📖 详细文档

🎯 功能导航

• 🎯 功能导航 - 从入门到精通 - 特色功能、实用功能、彩蛋功能完整索引

核心工具

• 📘 JSONMap & JSONList 完整指南 - JSON 数据处理核心工具
• 📗 核心工具集概览 - 所有工具的快速入门

应用场景

• 🎯 应用场景与痛点分析 - 四大核心场景、痛点对比、适用项目类型
• 🔥 @SetValue 注解指南 - 扁平 Bean ↔ 嵌套 JSON 双向映射
• 🤖 AI 友好开发指南 - 让 AI 生成的代码减少 90% 冗余

工具类文档

• 🔧 JacksonUtil - JSON 序列化与路径取值
• 📅 DateUtil - 日期时间处理
• 🔤 StringUtils - 字符串处理
• 🔄 ValUtil - 类型转换工具
• 💾 Cache - 缓存工具

---

💬 常见问题

Q: 这个工具代码看起来很新，有足够的测试吗？有 bug 吗？

放心，这套框架已经积累了近 20 年！

• 起源：从 2006 年职场小白开始，就在慢慢积累这套工具
• 验证：大大小小上百个内部项目都在使用，久经考验
• 测试：所有方法和案例都经过充分测试，有完整的测试用例覆盖
• 为什么看起来新：这是第一次开源上架，代码是从繁复的工程中精心剥离出来的，结构经过优化调整

20 年的积累，上百个项目的验证，稳定可靠！

Q: 适合 AI 辅助开发吗？

非常适合！ JSONMap 的设计理念就是简洁、直观，这正是 AI 喜欢的风格：

• AI 生成的代码减少 90% 冗余
• Token 消耗降低 90%
• 学习成本极低，AI 一看就懂

在 Cursor、GitHub Copilot 等 AI 工具中使用 JSONMap，可以显著提升代码生成质量。

Q: 我的项目没有 Jackson 怎么办？

添加 dlz.comm 会自动引入 Jackson，大多数 Spring 项目默认就有。

Q: 性能怎么样？

底层就是 LinkedHashMap，性能与原生 Map 一致。路径解析有缓存优化。

Q: 会和现有代码冲突吗？

不会。JSONMap 继承自 LinkedHashMap，可以当普通 Map 使用，完全兼容。

Q: Spring Boot 2.x / 3.x 都支持吗？

都支持。JSONMap 不依赖 Spring，只依赖 Jackson。

--- ## 🌟 Star History 如果觉得有帮助，请点个 ⭐ 支持一下！ ---

**用 1 行代码做完 10 行的事，这就是 JSONMap。** Made with ❤️ by DLZ