别再只引入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框架提供的集成支持

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

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

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

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

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); } }

关键配置点说明：

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

5. 性能优化建议

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

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

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

6. 迁移注意事项

从FastJson1迁移到FastJson2时，除了依赖变化外，还需要注意以下差异：

1. 包名变化：所有类从com.alibaba.fastjson改为com.alibaba.fastjson2
2. API变化：部分方法的签名和行为有所调整
3. 默认行为变化：一些特性的默认值与FastJson1不同
4. 注解支持：注解的使用方式可能有细微差别

建议的迁移步骤：

1. 先确保测试覆盖率足够
2. 逐个模块替换依赖
3. 更新所有import语句
4. 测试核心功能
5. 调整配置和特性设置
6. 全面回归测试