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

别再只引入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 groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2/artifactId version2.0.49/version /dependency核心库包含以下关键功能JSON解析和生成的基础API基本数据类型和集合类型的支持简单的注解支持性能优化的底层实现2.2 fastjson2-extension扩展库这个依赖提供了FastJson2的各种扩展功能特别是在Spring集成场景下很多关键类都位于这个模块中。dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2-extension/artifactId version2.0.49/version /dependency扩展库包含的重要功能FastJsonConfig配置类对各种JDK新特性的支持额外的注解和特性支持一些工具类和辅助功能提示即使你不使用Spring如果你的项目需要更丰富的JSON处理功能也应该考虑引入这个依赖。2.3 fastjson2-extension-spring6 Spring6适配库这是专门为Spring 6设计的适配模块包含了Spring MVC集成所需的所有类。dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2-extension-spring6/artifactId version2.0.49/version /dependency这个模块特别提供了FastJsonHttpMessageConverter实现Spring特定的类型转换支持与Spring框架深度集成的各种适配器针对Spring 6特性的优化实现3. 常见问题与解决方案3.1 类找不到错误分析当你在升级过程中遇到类似以下的错误时java.lang.ClassNotFoundException: com.alibaba.fastjson2.support.spring.http.converter.FastJsonHttpMessageConverter这通常意味着你缺少了必要的依赖。根据缺失的类可以判断缺少哪个模块缺失的类需要的依赖FastJsonHttpMessageConverterfastjson2-extension-spring6FastJsonConfigfastjson2-extensionJSON/JSONArray/JSONObjectfastjson23.2 Spring Boot版本兼容性FastJson2针对不同版本的Spring Boot提供了专门的适配模块Spring Boot 2.x使用fastjson2-extension-spring5Spring Boot 3.x/Spring 6使用fastjson2-extension-spring6如果你在Spring Boot 3.x项目中错误地引入了spring5的适配器虽然可能不会立即报错但可能会遇到一些微妙的兼容性问题。3.3 依赖版本一致性确保所有FastJson2相关依赖使用相同的版本号非常重要。混合使用不同版本可能导致难以诊断的问题。建议在Maven中使用属性来管理版本号properties fastjson2.version2.0.49/fastjson2.version /properties dependencies dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2/artifactId version${fastjson2.version}/version /dependency !-- 其他FastJson2依赖... -- /dependencies4. 完整配置示例下面是一个在Spring 6项目中完整配置FastJson2的示例Configuration public class WebMvcConfig implements WebMvcConfigurer { Override public void configureMessageConverters(ListHttpMessageConverter? 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-Type5. 性能优化建议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 );6. 迁移注意事项从FastJson1迁移到FastJson2时除了依赖变化外还需要注意以下差异包名变化所有类从com.alibaba.fastjson改为com.alibaba.fastjson2API变化部分方法的签名和行为有所调整默认行为变化一些特性的默认值与FastJson1不同注解支持注解的使用方式可能有细微差别建议的迁移步骤先确保测试覆盖率足够逐个模块替换依赖更新所有import语句测试核心功能调整配置和特性设置全面回归测试