Spring Boot项目升级FastJson2踩坑记：三个依赖缺一不可，附完整配置代码

Spring Boot项目升级FastJson2实战指南从依赖管理到配置优化最近在重构一个老项目时我决定将FastJson1升级到FastJson2版本。本以为只是简单修改下依赖版本号就能搞定结果却遭遇了各种类找不到的报错。经过两天折腾和源码研究终于摸清了FastJson2的模块化设计思路也总结出一套可靠的升级方案。1. 为什么FastJson2需要三个依赖FastJson2相比1.x版本最大的变化就是采用了模块化设计。官方将不同功能拆分成独立模块这种设计带来了更好的灵活性和更小的依赖体积但也让升级过程变得不那么直观。1.1 核心模块解析FastJson2的三个必要依赖各司其职fastjson2核心功能模块提供基础的JSON解析和生成能力fastjson2-extension扩展功能模块包含各种高级特性支持fastjson2-extension-spring6Spring专用适配器提供与Spring框架的深度集成!-- 必须同时引入这三个依赖 -- dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2/artifactId version2.0.49/version /dependency dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2-extension/artifactId version2.0.49/version /dependency dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2-extension-spring6/artifactId version2.0.49/version /dependency提示三个依赖的版本号必须保持一致否则可能出现兼容性问题1.2 常见缺失依赖的症状当缺少某个依赖时通常会遇到以下错误缺少fastjson2-extensionFastJsonConfig类找不到缺少fastjson2-extension-spring6FastJsonHttpMessageConverter类找不到缺少fastjson2基础JSON功能无法使用2. 配置类迁移指南从FastJson1升级到FastJson2配置类需要做多处调整。下面是一个完整的配置示例import com.alibaba.fastjson2.support.config.FastJsonConfig; import com.alibaba.fastjson2.support.spring6.http.converter.FastJsonHttpMessageConverter; Configuration public class WebMvcConfig implements WebMvcConfigurer { Override public void configureMessageConverters(ListHttpMessageConverter? converters) { FastJsonHttpMessageConverter converter new FastJsonHttpMessageConverter(); // 配置FastJson FastJsonConfig config new FastJsonConfig(); config.setDateFormat(yyyy-MM-dd HH:mm:ss); config.setCharset(StandardCharsets.UTF_8); // 配置序列化特性 config.setWriterFeatures( JSONWriter.Feature.WriteMapNullValue, JSONWriter.Feature.PrettyFormat ); // 配置反序列化特性 config.setReaderFeatures( JSONReader.Feature.FieldBased, JSONReader.Feature.SupportArrayToBean ); converter.setFastJsonConfig(config); converter.setSupportedMediaTypes(Collections.singletonList(MediaType.APPLICATION_JSON)); converters.add(0, converter); // 添加到首位 } }2.1 关键变更点对比配置项FastJson1FastJson2包路径com.alibaba.fastjsoncom.alibaba.fastjson2消息转换器类FastJsonHttpMessageConverterFastJsonHttpMessageConverter(位于spring6模块)配置类FastJsonConfigFastJsonConfig(位于extension模块)特性配置SerializerFeatureJSONWriter.Feature日期格式同FastJson2同FastJson13. 高级配置技巧3.1 自定义序列化规则FastJson2提供了更灵活的序列化控制FastJsonConfig config new FastJsonConfig(); // 配置全局命名策略 config.setPropertyNamingStrategy(PropertyNamingStrategy.SnakeCase); // 配置自定义序列化器 config.setWriterFilters(new ValueFilter() { Override public Object apply(Object object, String name, Object value) { if (value instanceof Date) { return ((Date) value).getTime(); } return value; } });3.2 性能优化建议复用配置对象FastJsonConfig是线程安全的建议作为单例使用合理选择特性不必要的特性会增加性能开销启用ASM加速FastJson2默认启用无需额外配置// 最佳实践配置示例 FastJsonConfig config new FastJsonConfig(); config.setWriterFeatures( JSONWriter.Feature.WriteMapNullValue, // 需要时才开启 JSONWriter.Feature.WriteBigDecimalAsPlain );4. 常见问题解决方案4.1 日期格式化问题FastJson2对日期的处理更加严格// 明确指定日期格式 config.setDateFormat(yyyy-MM-dd HH:mm:ss); // 或者使用时间戳 config.setWriterFeatures(JSONWriter.Feature.WriteDateUseTimestamp);4.2 循环引用处理// 启用循环引用检测 config.setWriterFeatures(JSONWriter.Feature.ReferenceDetection); // 或者禁用循环引用检测(性能更好) config.setWriterFeatures(JSONWriter.Feature.NotWriteDefaultValue);4.3 与Spring Boot的版本兼容性不同Spring Boot版本对应的依赖Spring Boot版本推荐FastJson2模块Spring Boot 3.xfastjson2-extension-spring6Spring Boot 2.xfastjson2-extension-spring55. 迁移后的验证与测试升级完成后建议进行以下验证基础功能测试简单对象序列化/反序列化集合类型处理日期时间处理性能对比使用相同数据集对比序列化速度检查内存占用情况边缘案例测试大整数处理特殊字符处理空值处理// 测试用例示例 Test public void testSerialization() { User user new User(); user.setName(测试); user.setCreateTime(new Date()); String json JSON.toJSONString(user); User parsed JSON.parseObject(json, User.class); assertEquals(user.getName(), parsed.getName()); }在实际项目中我建议先在一个非核心模块进行升级验证确认无误后再全量升级。同时保留回滚方案以防出现不可预期的问题。