https://github.com/dingkui/dlz-kit
像JavaScript一样在Java中“丝滑”操作JSON
https://github.com/dingkui/dlz-kit
Last synced: 4 days ago
JSON representation
像JavaScript一样在Java中“丝滑”操作JSON
- Host: GitHub
- URL: https://github.com/dingkui/dlz-kit
- Owner: dingkui
- Created: 2023-08-24T07:29:34.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2026-07-23T14:07:41.000Z (4 days ago)
- Last Synced: 2026-07-23T14:07:57.356Z (4 days ago)
- Language: Java
- Homepage:
- Size: 6.29 MB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# JSONMap — Java 嵌套数据操作，一行到位
[](LICENSE)
[]()
[]()
[](https://github.com/dingkui/dlz-kit)
```java
// 以前：10 行判空 + 强转，还可能 NPE
// 现在：1 行，没有中间对象，不会 NPE
String city = new JSONMap(response).getStr("data.user.profile.addresses[0].city");
```
```xml
top.dlzio
dlz-kit
6.6.6
```
---
## 30 秒上手
```java
// 解析 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 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。
```java
// 任意层级为 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
```
### 动态结构构建
```java
// 对比：传统方式需要逐层 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。
```java
Integer age = ValUtil.toInt(params.get("age")); // 不抛异常，返回 null 或正确值
Integer safe = ValUtil.toInt(params.get("age"), 0); // 带默认值
List 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 模型容易生成正确代码。
```java
// 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
- **测试**：完整测试用例覆盖
## 文档
- [快速上手](docs/第01章-快速入门/1.2-五分钟上手.md)
- [JSONMap 完整指南](docs/第02章-核心功能/2.1-JSONMap完整指南.md)
- [ValUtil 类型转换](docs/第03章-工具类库/3.1-ValUtil-类型转换.md)
- [@SetValue 注解映射](docs/第04章-高级特性/4.1-SetValue注解映射.md)
- [有界宽容原则](docs/第04章-高级特性/4.4-有界宽容原则.md)
- [性能测试报告](docs/第07章-附录/7.1-性能测试报告.md)
- [AI 速读指南](docs/AI-速读指南.md)（给 AI 模型看的快速参考）
---
如果觉得有用，点个 ⭐ 让更多人看到。