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

别再只引入`fastjson2`了！Spring 6整合FastJson2必须知道的三个Maven依赖

news 2026/6/4 0:59:22

别再只引入`fastjson2`了！Spring 6整合FastJson2必须知道的三个Maven依赖

如果你最近正在将项目从FastJson1升级到FastJson2，可能会遇到一些令人困惑的依赖问题。特别是当你在Spring 6环境中配置FastJsonHttpMessageConverter时，可能会频繁遇到"类找不到"的错误。这通常不是因为你的代码有问题，而是FastJson2在架构设计上做了重大改变——它将功能模块进行了更精细的拆分。

1. FastJson2的模块化设计理念

FastJson2相比FastJson1最大的架构变化就是采用了模块化设计。在FastJson1时代，几乎所有功能都打包在一个单一的JAR文件中，这虽然简化了依赖管理，但也带来了包体积过大、功能耦合度高的问题。

FastJson2将核心功能拆分成了三个主要模块：

fastjson2：包含JSON解析和生成的核心功能
fastjson2-extension：提供各种扩展功能，如对Kotlin的支持、JDK新特性的适配等
fastjson2-extension-spring6：专门为Spring 6框架提供的集成支持

这种设计带来了几个优势：

更小的依赖体积：可以只引入项目实际需要的模块
更清晰的职责划分：每个模块专注于特定领域
更好的兼容性：可以针对不同框架版本提供专门的适配

2. 三个关键依赖的详细解析

2.1 fastjson2核心库

这是FastJson2的基础依赖，提供了JSON处理的核心能力。无论你是否在Spring项目中使用FastJson2，这个依赖都是必须的。

<dependency> <groupId>com.alibaba.fastjson2</groupId> <artifactId>fastjson2</artifactId> <version>2.0.49</version> </dependency>

核心库包含以下关键功能：

JSON解析和生成的基础API
基本数据类型和集合类型的支持
简单的注解支持
性能优化的底层实现

2.2 fastjson2-extension扩展库

这个依赖提供了FastJson2的各种扩展功能，特别是在Spring集成场景下，很多关键类都位于这个模块中。

<dependency> <groupId>com.alibaba.fastjson2</groupId> <artifactId>fastjson2-extension</artifactId> <version>2.0.49</version> </dependency>

扩展库包含的重要功能：

FastJsonConfig配置类
对各种JDK新特性的支持
额外的注解和特性支持
一些工具类和辅助功能

提示：即使你不使用Spring，如果你的项目需要更丰富的JSON处理功能，也应该考虑引入这个依赖。

2.3 fastjson2-extension-spring6 Spring6适配库

这是专门为Spring 6设计的适配模块，包含了Spring MVC集成所需的所有类。

<dependency> <groupId>com.alibaba.fastjson2</groupId> <artifactId>fastjson2-extension-spring6</artifactId> <version>2.0.49</version> </dependency>

这个模块特别提供了：

FastJsonHttpMessageConverter实现
Spring特定的类型转换支持
与Spring框架深度集成的各种适配器
针对Spring 6特性的优化实现

3. 常见问题与解决方案

3.1 "类找不到"错误分析

当你在升级过程中遇到类似以下的错误时：

java.lang.ClassNotFoundException: com.alibaba.fastjson2.support.spring.http.converter.FastJsonHttpMessageConverter

这通常意味着你缺少了必要的依赖。根据缺失的类，可以判断缺少哪个模块：

缺失的类	需要的依赖
FastJsonHttpMessageConverter	fastjson2-extension-spring6
FastJsonConfig	fastjson2-extension
JSON/JSONArray/JSONObject	fastjson2

3.2 Spring Boot版本兼容性

FastJson2针对不同版本的Spring Boot提供了专门的适配模块：

Spring Boot 2.x：使用fastjson2-extension-spring5
Spring Boot 3.x/Spring 6：使用fastjson2-extension-spring6

如果你在Spring Boot 3.x项目中错误地引入了spring5的适配器，虽然可能不会立即报错，但可能会遇到一些微妙的兼容性问题。

3.3 依赖版本一致性

确保所有FastJson2相关依赖使用相同的版本号非常重要。混合使用不同版本可能导致难以诊断的问题。建议在Maven中使用属性来管理版本号：

<properties> <fastjson2.version>2.0.49</fastjson2.version> </properties> <dependencies> <dependency> <groupId>com.alibaba.fastjson2</groupId> <artifactId>fastjson2</artifactId> <version>${fastjson2.version}</version> </dependency> <!-- 其他FastJson2依赖... --> </dependencies>

4. 完整配置示例

下面是一个在Spring 6项目中完整配置FastJson2的示例：

@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void configureMessageConverters(List<HttpMessageConverter<?>> converters) { FastJsonHttpMessageConverter converter = new FastJsonHttpMessageConverter(); FastJsonConfig config = new FastJsonConfig(); config.setDateFormat("yyyy-MM-dd HH:mm:ss"); config.setReaderFeatures( JSONReader.Feature.FieldBased, JSONReader.Feature.SupportArrayToBean ); config.setWriterFeatures( JSONWriter.Feature.WriteMapNullValue, JSONWriter.Feature.PrettyFormat ); converter.setFastJsonConfig(config); converter.setDefaultCharset(StandardCharsets.UTF_8); converter.setSupportedMediaTypes(Collections.singletonList(MediaType.APPLICATION_JSON)); converters.add(0, converter); } }

关键配置点说明：

日期格式：统一设置日期序列化格式
Reader特性：配置反序列化时的行为
Writer特性：配置序列化时的行为
字符编码：明确指定UTF-8编码
媒体类型：声明支持的Content-Type

5. 性能优化建议

FastJson2在性能方面已经做了很多优化，但通过合理配置可以进一步提升：

复用配置对象：FastJsonConfig是线程安全的，可以在多个地方复用
选择合适的特性：根据实际需求开启特性，避免不必要的性能开销
考虑使用JSONB：对于高性能场景，FastJson2支持二进制JSON格式
合理配置缓存：FastJson2内部有多种缓存机制，适当调整缓存大小可以提高性能

// 性能优化配置示例 FastJsonConfig config = new FastJsonConfig(); config.setWriterFeatures( JSONWriter.Feature.WriteMapNullValue, JSONWriter.Feature.PrettyFormat, JSONWriter.Feature.LargeObject ); config.setReaderFeatures( JSONReader.Feature.FieldBased, JSONReader.Feature.UseNativeObject );