当前位置： 首页 > news >正文

Hutool-JSON 工具类超全使用指南：告别 JSON 处理繁琐操作

news 2025/11/16 7:03:07

在日常开发中，JSON 数据的序列化、反序列化、格式转换是高频需求。面对复杂的 JSON 处理场景，重复编写解析代码不仅效率低下，还容易出现格式错误。Hutool 作为 Java 开发中常用的工具包，其内置的 Hutool-JSON 模块通过简洁的 API 封装，让 JSON 处理变得高效便捷。本文将结合实际场景，详细讲解 Hutool-JSON 核心工具类的使用方法，助力开发者快速上手。

一、核心组件介绍

Hutool-JSON 的核心设计简洁明了，核心组件仅 3 个，各司其职且相互配合：

  • JSONUtil：静态工具类，提供 JSON 序列化、反序列化、格式转换等快捷方法，是操作 JSON 的入口。

  • JSONObject：对应 JSON 中的对象结构（大括号包裹的键值对），支持键值对的增删改查，兼具 Map 的灵活性和 JSON 的结构化特性。

  • JSONArray：对应 JSON 中的数组结构（中括号包裹的元素集合），支持数组元素的遍历、查询、转换，适配 List、数组等数据类型。

三者关系：JSONUtil 是 JSONObject 和 JSONArray 的“工具管家”，提供静态快捷方法；JSONObject 和 JSONArray 是具体的 JSON 数据载体，负责数据的存储和操作。

JSONObject代表一个JSON中的键值对象，这个对象以大括号包围，每个键值对使用,隔开，键与值使用:隔开，一个JSONObject类似于这样：

{"key1":"value1","key2":"value2"
}

在JSON中，JSONArray代表一个数组，使用中括号包围，每个元素使用逗号隔开。一个JSONArray类似于这样：

["value1","value2","value3"]

二、快速入门：基础操作指南

2.1 JSON 序列化（对象转 JSON 字符串）

将 Java 对象（Bean、Map、集合等）转换为 JSON 字符串，是接口返回、数据存储的常见需求，Hutool 提供了两种核心方法：

2.1.1 普通序列化（一行输出）

使用 JSONUtil.toJsonStr() 方法，支持任意对象的快速序列化，有序集合（如 TreeMap）会保留元素顺序：

// 示例1：有序Map序列化
SortedMap<Object, Object> sortedMap = new TreeMap<Object, Object>() {private static final long serialVersionUID = 1L;{put("attributes", "a");put("b", "b");put("c", "c");}
};
String jsonStr = JSONUtil.toJsonStr(sortedMap);
// 输出结果（有序）：{"attributes":"a","b":"b","c":"c"}// 示例2：Bean序列化（支持@Alias注解）
@Data
public class Test {private String name;@Alias("aliasSex") // 字段别名注解private String sex;
}Test test = new Test();
test.setName("handy");
test.setSex("男");
String beanJson = JSONUtil.toJsonStr(test);
// 输出结果：{"name":"handy","aliasSex":"男"}

2.1.2 格式化序列化（美观输出）

对于需要可读性的场景（如日志打印、接口调试），使用 JSONUtil.toJsonPrettyStr() 生成带缩进的格式化 JSON：

String prettyJson = JSONUtil.toJsonPrettyStr(sortedMap);
// 输出结果：
{"attributes": "a","b": "b","c": "c"
}

2.2 JSON 反序列化（JSON 字符串转对象）

将 JSON 字符串解析为 JSONObject、JavaBean、集合等，满足数据接收、解析的需求。

2.2.1 解析为 JSONObject

直接操作 JSON 键值对，无需定义 Bean，适合临时数据处理：

String jsonStr = "{\"name\":\"Something must have been changed since you leave\",\"age\":25}";
// 解析JSON字符串为JSONObject
JSONObject jsonObject = JSONUtil.parseObj(jsonStr);
// 获取字符串类型字段
String name = jsonObject.getStr("name");
// 获取整数类型字段（支持默认值，避免空指针）
int age = jsonObject.getInt("age", 0);
// 获取不存在的字段，返回默认值
String address = jsonObject.getStr("address", "未知地址");

2.2.2 解析为 JavaBean（支持复杂结构）

对于结构化数据，直接解析为 JavaBean 更便于业务处理，支持嵌套、泛型等复杂场景：

// 定义复杂Bean（含嵌套泛型）
@Data
public class ADT {private List<String> BookingCode;
}@Data
public class Price {private List<List<ADT>> ADT;
}// JSON字符串
String json = "{\"ADT\":[[{\"BookingCode\":[\"N\",\"N\"]}]]}";
// 解析为Bean
Price price = JSONUtil.toBean(json, Price.class);
// 访问嵌套字段
String bookingCode = price.getADT().get(0).get(0).getBookingCode().get(0);
// 输出结果：N

2.2.3 解析为 JSONArray 并操作

处理 JSON 数组格式数据，支持遍历、查询、转换为集合/数组：

// JSON数组字符串
String jsonArrStr = "[{\"id\":111,\"name\":\"test1\"},{\"id\":112,\"name\":\"test2\"}]";
// 解析为JSONArray
JSONArray jsonArray = JSONUtil.parseArray(jsonArrStr);// 1. 遍历数组
for (Object obj : jsonArray) {JSONObject jsonObj = (JSONObject) obj;System.out.println("id: " + jsonObj.getInt("id") + ", name: " + jsonObj.getStr("name"));
}// 2. 转换为JavaBean列表
List<User> userList = JSONUtil.toList(jsonArray, User.class);
// 访问第一个元素的id
int firstId = userList.get(0).getId(); // 输出：111// 3. 转换为数组
User[] userArray = jsonArray.toArray(new User[0]);// 4. 转换为Dict列表（Hutool自定义Map，支持类型安全获取）
List<Dict> dictList = JSONUtil.toList(jsonArray, Dict.class);
int dictId = dictList.get(0).getInt("id"); // 输出：111

三、进阶用法：解决复杂场景需求

3.1 JSON 与 XML 互转

在接口对接中，偶尔会遇到 XML 格式数据，Hutool 支持 JSON 与 XML 快速互转，无需额外依赖：

// 3.1.1 XML字符串转JSON
String xmlStr = "<sfzh>123</sfzh><sfz>456</sfz><name>aa</name><gender>1</gender>";
JSONObject xmlToJson = JSONUtil.parseFromXml(xmlStr);
String sfzh = xmlToJson.getStr("sfzh"); // 输出：123// 3.1.2 JSON转XML字符串
JSONObject jsonObj = JSONUtil.createObj().set("aaa", "你好").set("键2", "test");
String jsonToXml = JSONUtil.toXmlStr(jsonObj);
// 输出结果：<aaa>你好</aaa><键2>test</键2>

3.2 Bean 转 JSON 高级配置

默认情况下，Bean 转 JSON 可能存在字段顺序错乱、日期格式为时间戳、空值被过滤等问题，Hutool 提供了灵活的配置方案：

@Data
public class UserA {private String name;private String a;private Date date;private List<Seq> sqs;
}UserA userA = new UserA();
userA.setName("nameTest");
userA.setDate(new Date());
userA.setSqs(CollectionUtil.newArrayList(new Seq(null), new Seq("seq2")));// 配置1：保留空值 + 保持Bean字段顺序
JSONObject json = JSONUtil.parseObj(userA, false, true);// 配置2：自定义日期格式（默认时间戳）
json.setDateFormat("yyyy-MM-dd HH:mm:ss");// 输出结果（字段有序、日期格式化、空值保留）：
{"name": "nameTest","a": null,"date": "2024-05-20 14:30:00","sqs": [{"seq": null},{"seq": "seq2"}]
}

参数说明：

  • 第一个参数：待转换的 Bean 对象；

  • 第二个参数：false 表示不跳过空值（默认 true 过滤空值）；

  • 第三个参数：true 表示保持 Bean 字段顺序（默认 false 无序）。

3.3 JSON 路径查询（深层数据快速获取）

对于层级较深的 JSON 数据，传统的链式获取（如 json.getJSONArray(“a”).getJSONObject(0).getStr(“b”)）代码臃肿且易出错。Hutool 支持通过路径表达式快速获取目标值：

// 复杂JSON数组
String jsonStr = "[{\"id\": \"1\",\"name\": \"a\",\"detail\": {\"address\": \"北京\"}},{\"id\": \"2\",\"name\": \"b\"}]";
JSONArray jsonArray = JSONUtil.parseArray(jsonStr);// 路径表达式语法：数组索引用[]，对象字段用.
String name = jsonArray.getByPath("[1].name"); // 获取第二个元素的name，输出：b
String address = jsonArray.getByPath("[0].detail.address"); // 获取第一个元素的地址，输出：北京// 不存在的路径返回null，避免空指针
String noExist = jsonArray.getByPath("[2].age", "默认值"); // 输出：默认值

四、核心 API 汇总表

为了方便快速查阅，整理了 Hutool-JSON 最常用的 API 及说明：

功能场景核心方法说明
对象转 JSON 字符串JSONUtil.toJsonStr(Object obj)普通序列化，一行输出
对象转格式化 JSONJSONUtil.toJsonPrettyStr(Object obj)带缩进，可读性强
JSON 字符串转 JSONObjectJSONUtil.parseObj(String jsonStr)解析为键值对对象
JSON 字符串转 JSONArrayJSONUtil.parseArray(String jsonStr)解析为数组对象
JSON 转 JavaBeanJSONUtil.toBean(String jsonStr, Class clazz)支持复杂嵌套、泛型
JSONArray 转 ListJSONUtil.toList(JSONArray array, Class clazz)转换为指定类型的 List
XML 转 JSONJSONUtil.parseFromXml(String xmlStr)支持简单 XML 与 JSON 互转
JSON 转 XMLJSONUtil.toXmlStr(JSONObject jsonObj)生成 XML 字符串生成 XML 字符串生成 XML 字符串
深层数据获取getByPath(String path)路径表达式查询，支持数组和对象层级

五、使用注意事项

  1. 依赖引入：使用前需在项目中引入 Hutool 依赖（Maven 示例），建议使用最新版本：
<dependency><groupId>cn.hutool</groupId><artifactId>hutool-all</artifactId><version>5.8.28</version>
</dependency>

  1. 日期格式处理：默认日期会序列化为时间戳，若需自定义格式，可通过 json.setDateFormat(String pattern) 配置。

  2. 空值处理：JSONUtil.parseObj(bean, false) 可保留空值，适用于需要完整返回数据的场景（如接口响应）。

  3. 字段顺序：默认 JSON 字段无序，若需与 Bean 字段顺序一致，需设置第三个参数为 true（JSONUtil.parseObj(bean, false, true)）。

  4. 泛型支持：转换含泛型的 Bean 时（如 List），无需额外处理，Hutool 会自动解析泛型类型。

六、总结

Hutool-JSON 模块以“简洁、高效、易用”为核心，封装了 JSON 处理的常见场景，避免了重复造轮子。无论是简单的对象序列化、复杂的嵌套 Bean 解析，还是 XML 与 JSON 互转、深层数据查询，都能通过简洁的 API 快速实现。对于 Java 开发者而言，掌握 Hutool-JSON 能大幅提升 JSON 处理效率，让开发重心聚焦于业务逻辑而非工具类编写。

如果本文对你有帮助，欢迎点赞、收藏、转发～ 若有其他 Hutool 使用疑问或复杂场景需求，可在评论区留言交流！

http://www.dtcms.com/a/613992.html

相关文章：

  • 445 端口（SMB 服务）完整渗透流程总结
  • 咔咔做受视频网站摄影师网站建设
  • 大连建设网网址是多少啊重庆seo网站设计
  • TDengine 字符串函数 POSITION 用户手册
  • 燕郊建设局网站网站排名首页前三位
  • Docker容器使用手册——进阶篇（下）
  • C++入门指南：开启你的编程之旅
  • 智取能量：如何最大化战斗分数？
  • php网站开发技术要点网站模板制作流程
  • 进程和诊断工具速查手册（8.13）：VMMap / DebugView / LiveKd / Handle / ListDLLs 一页式现场排障清单
  • 【ros2】ROS2话题（Topic）通信完全指南：订阅与发布详解
  • 网站安全证书有问题如何解决网站地图如何做
  • 演练：使用VB开发多智能体协作的荣格八维分析器
  • 第8章 广播机制
  • 最近的一对
  • 网站设计建网站互联网是做什么的
  • 【C++】AVL树：详细使用及旋转
  • 网站开发技术的雏形 cgi满18点此转入2o2
  • 小华HC32L136K8TA 单片机新建 MDK5 工程模板(二)
  • Qt告警clazy-detaching-temporary浅谈
  • 前端构建工具扩展，Webpack插件开发
  • 拆解 LLM 的 “思考” 过程：推理机制深度解读
  • 《嵌入式成长系列之51单片机 --- Keil5创建工程》
  • 万米单波束EA640的raw数据处理
  • 成都公租房官方网站中南建设网官方网站
  • Cursor Chrome DevTools MCP 配置指南 for Windows
  • 汕头网站设计浩森宇特响应式网页设计图
  • 中职网站建设教学计划学网页设计软件开发
  • SpringBoot中Get请求和POST请求接收参数详解
  • 局部可变形模板匹配算法的初步实现