SpringBoot3整合FastJSON2：configureMessageConverters配置实战与避坑指南

SpringBoot 3 项目升级后原来在 SpringBoot 2 里用得挺顺的 FastJson 突然不干活了接口要么返回一串 Jackson 的默认格式要么直接报错排查几圈下来发现核心问题就出在configureMessageConverters这个配置方法上。这篇内容就围绕 SpringBoot3 整合 FastJSON2 的完整配置方式展开重点讲清楚configureMessageConverters怎么写、参数怎么调、踩过哪些坑以及怎么和logback-spring.xml、log4j2这类日志配置和平共处适合正在做 SpringBoot 版本升级、或者想把接口 JSON 序列化换成 FastJSON2 的朋友参考。1. 换到SpringBoot3后FastJSON2的集成方式为什么变了1.1 从Spring5到Spring6Fastjson扩展包必须跟着换SpringBoot3 底层的 Spring 框架直接从 Spring5 跳到了 Spring6包名从javax.*切成了jakarta.*很多第三方组件的适配方式也跟着调整。Fastjson2 比较特殊它把 Spring 的集成扩展包拆成了两套给 Spring5 及以下用的fastjson2-extension-spring5给 Spring6 / SpringBoot3 用的fastjson2-extension-spring6很多人升级以后只改了 fastjson2 的主包版本把com.alibaba.fastjson2:fastjson2升到最新结果FastJsonHttpMessageConverter一直包不存在或者方法签名不对原因就是没有引入对应的 Spring6 扩展包。我在项目里的依赖是这样写的dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2/artifactId version2.0.53/version /dependency dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2-extension-spring6/artifactId version2.0.53/version /dependency主包和扩展包的版本最好保持一致避免出现莫名其妙的方法找不到问题。如果项目里还同时用了 fastjson1 的老代码不要顺手再引fastjson那个老包两套序列化器混在一起会让排查成本直接翻倍。1.2 SpringBoot3自动配置不再照顾第三方JSON库SpringBoot 2 时代用了spring.mvc.converters.preferred-json-mapperfastjson这种配置方式配合第三方 starter 还能勉强生效。到了 SpringBoot3官方文档和自动配置逻辑里基本只保证 Jackson、Gson、JSON-B 这几类内置 JSON 方案Fastjson2 没有被纳入HttpMessageConvertersAutoConfiguration的候选列表。preferred-json-mapper这个配置项虽然还在但对 Fastjson 这种非官方库来说基本等于摆设。真正可靠的做法是在WebMvcConfigurer里手动接管configureMessageConverters方法把 FastJSON2 的转换器注册进去。另外要提醒一点如果实现了WebMvcConfigurer后又去继承WebMvcConfigurationSupportSpringBoot 的 MVC 自动配置会整体失效。常见表现是静态资源访问不了、拦截器失效、接口路径规则变化。项目里只要配置了 FastJSON2就不要再去碰WebMvcConfigurationSupport两者叠加很容易把环境搞成“看似配置了但实际没生效”的诡异状态。2. configureMessageConverters和extendMessageConverters选错会踩大坑2.1 两个方法的语义区别WebMvcConfigurer里提供了两个可以注册消息转换器的方法configureMessageConverters先由 SpringMVC 创建默认转换器列表再交给这个方法处理。如果方法内部调用了super.configureMessageConverters(converters)默认列表会保留如果不调用列表就会被清空完全由自己填充。extendMessageConverters在默认转换器列表已经构建完成之后追加自定义转换器不会影响默认列表的完整性。简单理解configureMessageConverters是“总闸”extendMessageConverters是“分流口”。如果只是想加一个 FastJSON2不需要动默认逻辑用extendMessageConverters更省事。但既然这篇是专门讲configureMessageConverters就要搞清楚它背后的几个细节。2.2 什么时候用configure什么时候用extend我实际项目中遇到的情况是项目里接入了很多老接口有的依赖 FastJson 的JSONField注解有的依赖自定义ValueFilter还有的依赖 long 转 string 的全局规则。这些需求用extendMessageConverters也能做但如果默认 Jackson 转换器排在前面SpringMVC 根据请求的Accept头和返回类型选择转换器时可能优先选中 JacksonFastJSON2 的全局配置就完全不会生效。所以“想彻底替换默认 JSON 行为”的场景必须走configureMessageConverters并且在方法里先调用super.configureMessageConverters(converters)再把 FastJSON2 转换器放到列表首位。这样既保留原有转换器兜底又能让 FastJSON2 拿到最高优先级。Override public void configureMessageConverters(ListHttpMessageConverter? converters) { super.configureMessageConverters(converters); FastJsonHttpMessageConverter fastJsonConverter new FastJsonHttpMessageConverter(); FastJsonConfig config new FastJsonConfig(); // ... 配置参数 fastJsonConverter.setFastJsonConfig(config); converters.add(0, fastJsonConverter); }如果只是某个模块或者某个接口想用 FastJSON2其他地方保持默认那用extendMessageConverters加在列表最后就够了影响范围更小也方便以后单独下线。总之默认行为与全局需求冲突时优先configureMessageConverters局部增强需求优先extendMessageConverters。3. SpringBoot3整合FastJSON2配置实操3.1 完整配置类configureMessageConverters写法先给出一份可以直接复制到项目里的完整配置类。这份配置包含了字符集、日期格式、空值输出、支持的 MediaType 等几项核心参数import com.alibaba.fastjson2.JSONReader; import com.alibaba.fastjson2.JSONWriter; import com.alibaba.fastjson2.support.config.FastJsonConfig; import com.alibaba.fastjson2.support.spring.http.converter.FastJsonHttpMessageConverter; import org.springframework.context.annotation.Configuration; import org.springframework.http.MediaType; import org.springframework.http.converter.HttpMessageConverter; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.List; Configuration public class WebJsonConfig implements WebMvcConfigurer { Override public void configureMessageConverters(ListHttpMessageConverter? converters) { // 保留默认转换器避免覆盖后丢失其他类型处理能力 super.configureMessageConverters(converters); FastJsonHttpMessageConverter converter new FastJsonHttpMessageConverter(); FastJsonConfig fastJsonConfig new FastJsonConfig(); // 全局日期格式覆盖 java.util.Date、LocalDate、LocalDateTime fastJsonConfig.setDateFormat(yyyy-MM-dd HH:mm:ss); fastJsonConfig.setCharset(StandardCharsets.UTF_8); // 序列化时输出为空的字段如果不想输出 null 字段可以去掉这一行 fastJsonConfig.setWriterFeatures( JSONWriter.Feature.WriteMapNullValue ); // 反序列化时忽略未知字段避免接口传入多余字段时报错 fastJsonConfig.setReaderFeatures( JSONReader.Feature.IgnoreNoneSerializable, JSONReader.Feature.FieldBased ); converter.setFastJsonConfig(fastJsonConfig); converter.setDefaultCharset(StandardCharsets.UTF_8); // 明确支持的 MediaType防止响应 Content-Type 出现乱码 ListMediaType mediaTypes new ArrayList(); mediaTypes.add(MediaType.APPLICATION_JSON); mediaTypes.add(MediaType.valueOf(application/json;charsetUTF-8)); mediaTypes.add(MediaType.valueOf(application/x-www-form-urlencoded)); converter.setSupportedMediaTypes(mediaTypes); // 放到最前面覆盖 Jackson 的优先匹配 converters.add(0, converter); } }这份配置有几个细节需要特别说明super.configureMessageConverters(converters)这一步不能省。如果不调用 superSpringMVC 默认的StringHttpMessageConverter、ByteArrayHttpMessageConverter、MappingJackson2HttpMessageConverter等都会被丢掉接口返回 String 类型时可能直接变成 JSON 字符串带引号或者出现“返回的内容被二次序列化”的怪事。converters.add(0, converter)也很关键。FastJSON2 转换器虽然支持application/json但 SpringMVC 会按列表顺序匹配转换器默认 Jackson 排在前面的话FastJSON2 的全局特性就用不上。把它放在索引 0就能保证优先匹配。3.2 配置参数细节日期、空值、Long精度FastJSON2 的FastJsonConfig提供了setWriterFeatures和setReaderFeatures两个入口分别控制序列化和反序列化行为。实际项目里最常用的几个特性如下特性作用常见用法JSONWriter.Feature.WriteMapNullValue序列化时输出值为 null 的字段前端需要判断字段存在性时使用JSONWriter.Feature.WriteNullStringAsEmptynull 字符串输出为空串对老接口兼容性要求高时使用JSONWriter.Feature.WriteNullListAsEmptynull 列表输出为空数组返回列表字段时建议开启JSONWriter.Feature.PrettyFormat格式化 JSON 输出调试阶段方便看结构JSONReader.Feature.IgnoreNoneSerializable忽略没有实现 Serializable 的字段处理第三方类时防止序列化失败JSONReader.Feature.FieldBased基于字段反序列化不依赖 setter处理只有 getter 的只读对象时很香日期格式方面fastJsonConfig.setDateFormat(yyyy-MM-dd HH:mm:ss)是全局日期格式但如果某些字段需要返回时间戳或者yyyy-MM-dd可以用JSONField(format yyyy-MM-dd)单独覆盖import com.alibaba.fastjson2.annotation.JSONField; public class UserVO { JSONField(format yyyy-MM-dd) private LocalDate birthday; JSONField(format yyyy-MM-dd HH:mm:ss) private LocalDateTime createTime; }这里要特别提醒FastJSON2 对LocalDateTime和Date的处理方式不太一样。只设置全局 dateFormat 时LocalDateTime有可能被序列化成数组格式或者 ISO 字符串最好在实体字段上显式加JSONField(format yyyy-MM-dd HH:mm:ss)省得联调时被前端追问“为什么日期变成了一串数字”。Long 精度丢失是另一个高频问题。前端 JavaScript 的 Number 类型只能安全表示2^53以内的整数后端主键如果用了雪花算法生成 Long 类型转成 JSON 后前端会拿到一个不精确的数值。FastJSON2 里可以通过ValueFilter把超过安全范围的 Long 转成字符串import com.alibaba.fastjson2.filter.ValueFilter; public class LongToStringFilter implements ValueFilter { private static final long MAX_JS_SAFE_NUMBER 9007199254740991L; Override public Object process(Object object, String name, Object value) { if (value instanceof Long) { Long longValue (Long) value; if (longValue MAX_JS_SAFE_NUMBER || longValue -MAX_JS_SAFE_NUMBER) { return longValue.toString(); } } return value; } }然后在配置类里把 filter 挂到FastJsonConfigfastJsonConfig.setWriterFilters(new LongToStringFilter());这样全局生效不需要在每个实体类的主键字段上手动加注解省心很多。3.3 局部使用FastJSON2的两种姿势如果不想全局替换 Jackson只想在某些接口里用 FastJSON2有两种轻量方式。第一种是在 Controller 方法上直接返回 String然后用 FastJSON2 工具类序列化对象GetMapping(/user) public String getUser() { UserVO user userService.getById(1L); return JSON.toJSONString(user); }这种方式简单直接但丢失了JSONField之外的全局配置日期和空值策略都需要自己处理。适合临时验证或个别接口特殊处理。第二种是使用JSONField注解配合局部HttpMessageConverter。比如某个接口的 DTO 只希望在当前 Controller 内使用 FastJSON2 序列化可以在配置类里注册一个局部变量或者直接通过MappingJacksonValue手动指定序列化器。实际项目中用第一种方式更多因为大部分团队更看重统一规范和排查效率。3.4 配置后如何验证是否生效配置完成后最直接的验证方式是在任意 Controller 里返回一个包含 null 字段和 LocalDateTime 字段的对象看返回 JSON 是否符合预期。RestController public class TestController { GetMapping(/test) public MapString, Object test() { MapString, Object result new LinkedHashMap(); result.put(name, 张三); result.put(age, null); result.put(now, LocalDateTime.now()); return result; } }如果配置生效返回结果应该是name和now有值age字段也会在启用了WriteMapNullValue的情况下出现日期格式是yyyy-MM-dd HH:mm:ss。如果返回内容还是 Jackson 风格例如now变成时间戳数组说明转换器优先级没调整对检查converters.add(0, converter)是否真的执行了。4. 我踩过的几个坑照着查能省半天时间4.1 配置完不生效最常见的原因有三个第一项目里存在多个配置类同时实现了WebMvcConfigurer后加载的配置类把先加载的转换器列表覆盖了。这种情况可以通过在configureMessageConverters方法里加日志输出来排查看看执行顺序和最终列表里的转换器个数。第二WebMvcConfigurationSupport被某个配置类继承了导致自动配置失效。需要全局搜索extends WebMvcConfigurationSupport的类确认是不是以前的旧代码遗留下来的。第三SpringBoot 3 里如果使用了spring-boot-starter-webflux响应式 Web而不是spring-boot-starter-webWebMvcConfigurer这套配置根本不生效因为 WebFlux 走的是WebFluxConfigurer和ReactiveHttpMessageConverter那套机制。项目如果同时引入了 web 和 webflux配置方向要确认清楚。4.2 LocalDateTime序列化成奇怪格式FastJSON2 对 Java8 时间类型的支持依赖fastjson2主包里的Jdk8TimeModule但该模块在某些版本里默认不自动注册需要手动激活FastJsonConfig config new FastJsonConfig(); config.setWriterFeatures(JSONWriter.Feature.WriteClassName);不过更稳妥的做法是实体字段上加JSONField(format yyyy-MM-dd HH:mm:ss)。全局配置和字段注解同时存在时字段注解优先级更高这样就不会因为某个 LocalDateTime 字段没加注解而出现格式混乱。4.3 Long精度丢失前面提到了LongToStringFilter但如果项目里某个字段只是偶尔超长也可以直接在字段上加注解JSONField(serializeUsing ToStringSerializer.class) private Long orderId;ToStringSerializer类在 fastjson2 的扩展包里包路径是com.alibaba.fastjson2.support.spring.http.converter下面的工具类实际使用时要引入fastjson2-extension-spring6依赖。对于只需要处理个别字段的场景局部注解比全局 filter 影响范围小推荐优先考虑。4.4 null字段凭空消失FastJSON2 默认对 null 字段的输出策略和 FastJSON1 不完全一样。FastJSON1 需要WriteMapNullValue才能输出 nullFastJSON2 在某些配置组合下即使设置了WriteMapNullValueMap 里的 null 值和 Bean 里的 null 值行为也可能不同。实际联调时如果发现前端拿不到某些字段优先检查setWriterFeatures里有没有JSONWriter.Feature.WriteMapNullValue以及该字段是不是 Map 类型。另外如果 bean 里设置了JSONField(serialize false)的字段这类字段无论怎么配都不会输出不要误认为是转换器配置问题。4.5 升级后日志配置一起坏掉的连带问题标题里提到springboot3 log4j2和springboot3 logback-spring.xml这个搜索热度不是没道理的。升级 SpringBoot3 时很多人会顺手调整日志框架最常见的问题是logback-spring.xml里的 Spring 占位符失效或者引入了 log4j2 依赖后日志完全静默。我用 FastJSON2 做接口序列化的项目里就遇到过日志框架切换时因为 pom 里没有排除spring-boot-starter-logging导致 logback 的配置根本不加载。处理方式很简单在引入 log4j2 时显式排除掉默认 logbackdependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-logging/artifactId /exclusion /exclusions /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-log4j2/artifactId /dependency如果继续使用 logback则要检查logback-spring.xml里是否引用了application.yml中不存在的属性。SpringBoot3 里部分配置项名字做了调整比如logging.level相关配置没有变但server.port在 logback 里通过${server.port}引用时可能拿不到值需要改成${SERVER_PORT}环境变量或者硬编码测试端口。日志配置和 JSON 配置本身没有直接关系但经常在同一轮升级中一起被改坏所以排查问题时把日志和消息转换器分开看不要在一个问题上钻牛角尖。4.6 配置与Swagger接口文档冲突项目里如果使用了springdoc-openapi这类接口文档组件替换掉 Jackson 转换器后Swagger 的 JSON 响应可能格式异常甚至接口文档加载不出来。这是因为springdoc内部也依赖 Jackson 来序列化文档对象。我的处理方案是configureMessageConverters里保留super的默认转换器同时把 FastJSON2 放到最前面。这样业务接口走 FastJSON2而 springdoc 内部如果显式注入了 Jackson 转换器还能继续工作。如果业务接口确实需要 FastJSON2而文档接口需要 Jackson还可以在 springdoc 的配置类里单独指定springdoc.api-docs.path对应的转换器避免全局互相干扰。5. 几种替代方案对比为什么我最终留在fastjson25.1 与Jackson对比Jackson 是 SpringBoot 默认方案复杂对象和泛型处理能力很强生态也最完整。但 Jackson 的ObjectMapper配置往往需要在多个地方定制尤其是 LocalDateTime 序列化、null 值处理、字段命名策略等。FastJSON2 的优势在于 API 风格比较集中FastJsonConfig一个类就能搞定大部分全局配置加上JSONReader.Feature.FieldBased这类快速增强特性在处理老系统遗留的 getter/setter 不规范的类时很顺手。性能上两者在实际业务中差别不大除非是超大量 JSON 吞吐的网关或者性能敏感场景否则不需要单纯为了性能从 Jackson 切换到 FastJSON2。5.2 与Gson/JSON-B对比Gson 轻量但对 Java8 时间类型支持不够完整JSON-B 在 SpringBoot 里的自动配置并不成熟。FastJSON2 的社区文档和中文资料更多遇到问题搜索方案也比较快这是国内团队选择它的一个实际理由。5.3 我的选择标准FastJSON2 适合以下情况项目里已经有大量JSONField注解和自定义 filter 的老代码需要全局统一日期格式、null 输出策略、Long 精度处理团队成员对 Fastjson 系列 API 更熟悉维护成本更低需要针对第三方的只读对象或者不规范 bean 做反序列化如果项目从零开始团队对 Jackson 也很熟那优先用 SpringBoot3 自带 Jackson 完全没问题。我这个项目之所以坚持 FastJSON2主要是因为历史 DTO 里的JSONField注解太多迁移成本高而且部分接口依赖 Fastjson2 对Map和JSONObject的特殊处理。6. 实际项目中的一点额外建议在 SpringBoot3 里配置 FastJSON2 这步做完以后我建议顺手做两件小事第一统一封装一个FastJsonConfig工具方法。因为项目里可能不止 WebMvc 在用 FastJSON2日志打印、定时任务、MQ 消息体序列化都可能用到。把这部分配置抽成一个静态方法返回配置好的FastJsonConfigWebMvc 和业务代码共用一套配置避免出现“接口返回的日期格式和日志打印的日期格式不一致”这种问题。第二加一个集成测试来防止回归。比如写一个SpringBootTest通过MockMvc请求一个返回LocalDateTime和null字段的接口断言 JSON 里的关键字段。以后有人不小心改了转换器配置或者调整了依赖顺序测试能第一时间暴露问题不用等前端联调才发现。我自己的实操体会是configureMessageConverters这块配置本身不难真正消耗时间的是理解 SpringMVC 消息转换器的工作机制以及和 SpringBoot3 自动配置之间的优先级关系。先把转换器列表的匹配顺序吃透再动手配置 FastJSON2基本能把 90% 的兼容性问题挡在门外。