SpringBoot中JSON工具类JsonUtils的实践教学

Spring Boot 项目里，JSON 工具类几乎是每个 Service 都绕不开的基础设施。但选哪个 JSON 库一直是个让人头疼的选择题：Fastjson2 性能确实快，可它背着历史安全包袱；Jackson 稳如老狗，配置起来却能把人绕晕；Fastjson1 还在老项目里赖着不走，谁都不想接手维护。更要命的是，一旦业务代码直接绑定了某个库的 API，将来想换库就得全局翻修，牵一发动全身。

这时候 JsonUtils 的思路就很有意思了——统一接口加启动时自动检测 JSON 库，三套引擎无缝切换。业务代码只管调 JsonUtils.parseObject()，底层用的是 Fastjson2、Jackson 还是 Fastjson1，完全由 classpath 上的依赖说了算。

引入依赖，直接开始用

Spring Boot 2.x 项目：

  com.gitee.apanlh
  apanlh-common
  2.0.6

Spring Boot 3.x 项目：

  com.gitee.apanlh
  apanlh-common
  3.0.6

JDK 8+ 都能跑。三个 JSON 库（Fastjson2、Jackson、Fastjson1）都是可选依赖，项目里引了哪个就用哪个，无需额外配置。

最简单的用法：3 分钟上手

JSON 转 Bean

import com.gitee.apanlh.util.dataformat.JsonUtils;
import com.gitee.apanlh.util.dataformat.TypeReference;

// JSON 字符串转 Bean
User user = JsonUtils.parseObject("{"name":"Pan","age":28}", User.class);

// 带泛型的复杂类型，用 TypeReference 避免类型擦除
Map> map = JsonUtils.parseObject(json,
    new TypeReference>>() {});

// JSON 数组转 List
List users = JsonUtils.parseArray(jsonArray, User.class);

Bean 转 JSON

// 对象转 JSON 字符串
String json = JsonUtils.toJson(user);

// 对象转 JSON 字节数组（UTF-8）
byte[] bytes = JsonUtils.toJsonBytes(user);

解析为 Map

// 转为标准 HashMap，不是 JSONObject
Map map = JsonUtils.parseToMap(json);

// 保持插入顺序的 LinkedHashMap
Map linked = JsonUtils.parseToLinkedMap(json);

// 按键自然排序的 TreeMap
Map sorted = JsonUtils.parseToSortedMap(json);

// JSON 数组转为 List

所有 parseTo* 方法返回的都是标准 Ja va 容器（HashMap、ArrayList），不会出现 JSONObject 或 JSONArray 这类库专有类型。嵌套结构也会递归转换。

对象类型转换

// 把 Map、List 或其他对象转为指定类型
Map map = JsonUtils.parseToMap(json);
User user = JsonUtils.to(map, User.class);

三引擎自动检测

底层用 JsonProvider 接口抽象了三套实现，启动时自动选择：

检测优先级：Fastjson2 > Jackson > Fastjson1

classpath 上有什么就用什么，业务代码永远只写 JsonUtils.parseObject()，底层引擎换了，调用方完全无感知。

每种引擎都配好了安全默认值：

Fastjson2 Provider

• 启用 UseNativeObject 特性，解析结果直接使用原生 Ja va 对象
• 所有 JSONObject/JSONArray 递归转为标准 Map/List

Jackson Provider

• 注册 Ja vaTimeModule，日期序列化输出可读字符串 yyyy-MM-dd HH:mm:ss.SSS，不是时间戳
• FAIL_ON_UNKNOWN_PROPERTIES = false，默认忽略未知字段
• USE_BIG_DECIMAL_FOR_FLOATS = true，统一浮点数为 BigDecimal，避免精度丢失

Fastjson1 Provider

• AutoTypeSupport = false，关闭自动类型识别，防止反序列化漏洞
• 关闭循环引用检测 DisableCircularReferenceDetect
• 日期序列化使用全局格式 WriteDateUseDateFormat

统一日期解析

不同 JSON 库对 LocalDateTime、LocalDate、Date 的解析规则各不相同。Fastjson 认 "2024-01-15 10:30:45"，Jackson 默认只认 ISO 格式 "2024-01-15T10:30:45"——这一差异在实际项目中踩过坑的应该都懂。

三套 Provider 内部都委托给了 DateParserUtils，所以不管用哪个 JSON 库，日期解析行为完全一致：

// 三种库都能正确解析这些日期字符串
String json = "{"createTime":"2024年1月15日"}";
User user = JsonUtils.parseObject(json, User.class);
// user.createTime → 2024-01-15T00:00:00

实用功能

JSON 格式校验

JsonUtils.hasJson("{"name":"test"}");       // true
JsonUtils.hasJson("not json");                  // false

JsonUtils.hasJsonArray("[1,2,3]");              // true
JsonUtils.hasJsonArray("{"a":1}");            // false

JsonUtils.hasJsonObject("{"a":1}");           // true
JsonUtils.hasJsonObject("[1,2,3]");             // false

字节数组直接解析

网络传输经常拿到 byte[]，不用自己转 String：

byte[] jsonBytes = ...;
List users = JsonUtils.parseArray(jsonBytes, User.class);

JSON 行格式输出

日志记录、行式 JSON 文件生成场景：

List users = Arrays.asList(new User("A"), new User("B"));

// 每行一个 JSON 对象
String lines = JsonUtils.toJsonLines(users);
// {"name":"A"}
// {"name":"B"}

// 自定义分隔符
String delimited = JsonUtils.toJsonDelimited(users, ";");
// {"name":"A"};
// {"name":"B"}

手动指定 Provider

自动检测能满足绝大多数场景，但如果确实想强制用某个库：

import com.gitee.apanlh.util.dataformat.JsonUtils;
import com.gitee.apanlh.util.dataformat.FastJson2Provider;

// 应用启动时设置一次，后续所有调用都用这个 Provider
JsonUtils.setProvider(new FastJson2Provider());

建议在 @PostConstruct 或 @Configuration 里设置。设置后会覆盖自动检测结果。

不适合的场景

• 需要精细控制 ObjectMapper/ParserConfig 的：可以继承对应 Provider 重写 getMapper() / getParserConfig()，但深度定制场景直接用自己的 ObjectMapper 可能更合适
• 不支持 JWE（JSON 加密）
• 不提供 JSON Patch / JSON Pointer

总结

JsonUtils 的核心就一句话：一个统一接口覆盖三套 JSON 引擎，启动自动检测，换库零改动。比起自己封装一层“JsonUtil”，它把自动检测、日期统一、安全默认值这些坑都提前填了。parseToMap 返回标准 Ja va 容器而不是库专有类型，日期解析走统一路由避免各库行为不一致，每个 Provider 都有经过验证的安全默认值（Fastjson 关 AutoType、Jackson 忽略未知字段）。日常开发中基本不需要操心中间层的差异。

适合场景：Spring Boot Web 项目、需要统一 JSON 操作 API、未来可能换 JSON 库、希望各模块日期解析行为一致。

不适合场景：需要深度定制 ObjectMapper、需要 JWE/JSON Patch 等高级 JSON 特性。