1. 项目背景与问题初现最近在负责一个老项目的技术栈升级其中一个核心任务是把项目中使用的 fastjson 从 1.2.83 版本升级到最新的 2.0.9 版本。这个决定背后有多重考量一方面是 fastjson 1.x 系列爆出的多个高危反序列化漏洞比如那个著名的 1.2.47 远程命令执行漏洞让运维同学天天提心吊胆另一方面fastjson2 作为阿里官方的下一代序列化库在性能、安全性和 API 设计上都宣称有巨大改进长期来看是必然的选择。升级过程本身不算复杂Maven 依赖一改重新编译大部分测试用例也都跑过了。但就在我们以为可以松一口气的时候线上一个不太起眼的监控告警把我们拉回了现实有几个接口返回的 JSON 数据中某些字段名“莫名其妙”地变了导致前端解析失败页面直接报错。具体现象是一个UserDTO对象在 1.2.83 下序列化后字段是{userName:张三,userId:123}到了 2.0.9 下竟然变成了{username:张三,userid:123}。字段名从驼峰变成了全小写这直接导致了前后端契约的破坏。这可不是小问题在微服务架构下这种序列化不一致就像一颗定时炸弹可能引发上游服务、消息队列消费者乃至数据存储的一系列连锁反应。我意识到这次升级远不是改个版本号那么简单fastjson2 在带来新特性的同时也引入了一些默认行为的改变而我们之前对 1.x 的“经验”和“潜规则”理解在这里可能不再适用。这次踩坑经历让我对 fastjson 的版本差异和升级策略有了更深刻的认识也整理出了一套完整的排查和解决方案。2. 核心问题深度剖析属性名映射规则之变为什么字段名会变这是首先要搞清楚的问题。在 fastjson 1.x 时代默认的命名策略PropertyNamingStrategy是CamelCase这也是 Java 世界最常用的约定类中的userName字段序列化成 JSON 时默认就是userName。然而fastjson 2.x 在默认行为上做了一个重大的、但文档中并不显眼的调整。2.1 fastjson 2.x 的默认命名策略fastjson 2.0 引入了一个新的默认命名策略PropertyNamingStrategy.CamelCase1x。这个名字有点迷惑性它其实是为了“模拟” fastjson 1.x 的行为但又不完全一样。更关键的是在 2.x 中还存在着另一个策略叫PropertyNamingStrategy.CamelCase。这两者的区别非常微妙但正是问题的根源。经过阅读源码和测试我发现CamelCase1x 这是 fastjson 2.x默认的策略。它的目标是尽可能兼容 1.x 的行为。对于标准的 Getter/Setter如getUserName/setUserName它能正确推导出字段名userName。但是它的兼容逻辑存在一些边界情况。CamelCase 这是一个“更标准”或“更严格”的驼峰策略。在某些特定情况下它的推导逻辑与CamelCase1x不同。在我们的案例中问题出在实体类的字段命名和 Lombok 的使用上。我们大量使用了 Lombok 的Data注解来生成 Getter/Setter。对于字段userNameLombok 生成的 Getter 是getUserName()。在 fastjson 1.2.83 的CamelCase策略下它能正确识别并序列化为userName。但在 fastjson 2.0.9 的默认CamelCase1x策略下其内部推导逻辑可能将这个 Getter 方法名先转换为userName去掉get并首字母小写然后可能又经过了一层全小写化的处理或者是遇到了某些特定字符序列的规则最终错误地输出了username。这种细微的差异在简单的 POJO 上可能不会出现但在字段名包含多个大写字母如userId-userid或特定缩写时就容易暴露出来。2.2 Feature 配置的差异与影响除了命名策略fastjson 2.x 在Feature配置上也做了大量重构和新增。Feature是控制序列化/反序列化行为的开关集合。很多在 1.x 中默认开启或关闭的特性在 2.x 中可能发生了变化。例如在 1.x 中Feature.WriteMapNullValue用于控制是否输出值为null的字段默认是false。而在 2.x 中相关的配置可能被整合或重命名。虽然这不是我们当前字段名问题的直接原因但在升级过程中如果忽略了Feature的差异很可能导致 JSON 输出的结构发生变化比如突然多出一堆null字段或者原本输出的字段不见了同样会破坏接口契约。另一个需要关注的Feature是Feature.IgnoreNoneSerializable。在 1.x 中如果序列化的对象含有不可序列化的字段例如一个Thread类型的成员默认会抛出异常。而在 2.x 中这个行为的默认值可能不同或者需要通过其他配置项来控制。如果我们的 DTO 中不小心混入了非序列化对象升级后可能从“报错”变为“静默忽略”这反而会掩盖问题导致数据丢失。注意fastjson 2.x 的Feature枚举类 (com.alibaba.fastjson2.JSONWriter.Feature) 与 1.x (com.alibaba.fastjson.serializer.SerializerFeature) 是完全不同的包和类。不能简单地通过import修改来迁移配置必须逐一核对每个Feature在 2.x 中的对应项和默认值。3. 系统性排查与诊断流程当发现属性转换不一致的问题后不能头痛医头脚痛医脚需要一个系统性的排查流程来定位所有潜在的风险点。我总结为“四步诊断法”。3.1 第一步全局扫描与差异对比首先我们需要知道到底有多少地方受到了影响。手动检查是不可能的必须借助工具进行自动化扫描。编写差异对比工具 我写了一个简单的 Java 工具利用反射扫描项目中所有标记了RestController、ResponseBody或类似注解的返回值类型以及所有显式调用JSON.toJSONString()的类。然后针对每个候选的 POJO 类分别用 fastjson 1.2.83 和 2.0.9 实例化一个具有典型值的对象并进行序列化最后比较两个 JSON 字符串。这里的关键是实例化对象时要填充有区分度的数据比如字段名本身就包含大小写变化userName,URL,IDCard等。// 示例对比逻辑片段 Object sampleObj createSampleInstance(clazz); // 根据类信息构造一个样例对象 String json1 com.alibaba.fastjson.JSON.toJSONString(sampleObj); // 1.x String json2 com.alibaba.fastjson2.JSON.toJSONString(sampleObj); // 2.x if (!json1.equals(json2)) { // 记录下这个类名和差异详情 logger.warn(Class {} has serialization difference., clazz.getName()); // 进一步解析差异是字段名不同还是值不同 }分析差异类型 对比结果可能显示几种差异字段名变化如userName-username。这是最需要关注的。字段顺序变化fastjson 2.x 默认的字段顺序可能与 1.x 不同。虽然 JSON 标准不要求顺序但某些前端库或测试用例可能依赖顺序。null 字段处理某些字段在 1.x 输出在 2.x 被忽略或反之。日期/数字格式默认的日期格式可能从时间戳变成了字符串。3.2 第二步聚焦问题类定位根因对于第一步筛选出的问题类需要深入分析。我们的问题集中在字段名上所以重点排查检查类定义 查看类的字段名、Getter/Setter 方法名。特别注意 Lombok、MapStruct 等代码生成工具生成的方法是否符合预期。有时候手写的 Getter 方法例如getURL()也可能导致解析差异。检查注解 fastjson 提供了JSONField注解来显式指定序列化行为。检查问题类上是否使用了该注解特别是name属性。确保 1.x 和 2.x 的注解包路径正确1.x:com.alibaba.fastjson.annotation.JSONField, 2.x:com.alibaba.fastjson2.annotation.JSONField。如果混用注解会失效。使用调试工具 在测试环境中针对问题接口或方法分别用两个版本的 fastjson 进行序列化并调试进入toJSONString方法内部。观察在CamelCase1x策略下序列化器是如何从getUserName()方法名推导出最终字段名的。这能最直观地看到逻辑分歧点。3.3 第三步审查全局配置与自定义序列化器很多项目会在启动时如 Spring Boot 的Configuration类中配置全局的 fastjsonSerializeConfig或ParserConfig或者注册自定义的ObjectSerializer/ObjectDeserializer。全局配置 检查项目中是否有类似JSON.DEFAULT_PARSER_FEATURE或SerializeConfig.getGlobalInstance().put(...)的代码。这些全局配置在升级后必须重新评估。fastjson 2.x 的配置入口通常是JSONFactory和JSONReader.Context/JSONWriter.Context。自定义序列化器 这是高风险区。为特定类如枚举、LocalDateTime编写的自定义序列化器其接口在 2.x 中可能已经改变。必须逐个检查这些类确保它们实现了 2.x 对应的接口如ObjectWriter并且逻辑兼容。Spring HttpMessageConverter 配置 如果项目使用 Spring MVC 并配置了 FastJsonHttpMessageConverter需要检查其配置。在 2.x 中对应的类是FastJson2HttpMessageConverter。要确保其中设置的Features、SerializeFilters等与 1.x 时期的行为一致。3.4 第四步制定并验证修复方案根据排查结果制定针对性的修复方案。我们的核心问题是默认命名策略解决方案有以下几种需要根据实际情况选择或组合方案一显式使用JSONField注解推荐这是最彻底、最可控的方式。在每一个需要序列化的字段或其 Getter 方法上添加JSONField(name “xxx”)来显式指定序列化后的字段名。这样无论底层命名策略如何变化输出都是确定的。优点 行为明确不受版本升级影响代码即文档。缺点 如果 POJO 数量众多改动量较大。但可以通过 IDE 的批量重构功能部分解决。实操 确保导入的是com.alibaba.fastjson2.annotation.JSONField。public class UserDTO { JSONField(name userName) private String userName; JSONField(name userId) private Long userId; // getters and setters }方案二调整全局命名策略如果不想大规模修改注解可以尝试在应用启动时将 fastjson 2.x 的全局命名策略改回更接近 1.x 行为的模式。但要注意这可能会影响所有序列化行为需要充分测试。操作 在 Spring Boot 主类或配置类中通过JSONFactory.setDefaultObjectWriterProvider或配置HttpMessageConverter时传入自定义的JSONWriter.Context来设置命名策略。可以尝试PropertyNamingStrategy.CamelCase而非默认的CamelCase1x看是否能解决问题。风险 “更接近”不等于“完全相同”。这个方案可能解决了 A 类的问题却在 B 类上引发了新问题。必须进行全面的回归测试。方案三使用 Fastjson 2.x 的兼容模式fastjson 2.x 提供了一些旨在兼容 1.x 的 API 和配置。例如可以使用com.alibaba.fastjson2.JSON类中那些以toJSONString(Object, JSONWriter.Feature...)形式存在的方法并传入特定的Feature。但根据我的测试对于命名策略这种底层行为仅通过Feature很难完美复现 1.x 的所有细节。建议 不要过度依赖“兼容模式”它可能只是一个临时方案。明确指定行为方案一才是长期稳定的保障。修复后的验证 修改完成后必须重新运行第一步的全局差异对比工具确保所有不一致都已消除。此外要跑遍所有的单元测试、集成测试和 API 契约测试如果有的话。特别要关注那些依赖 JSON 字段顺序或精确字符串匹配的测试用例。4. 升级全流程实操指南与避坑要点基于这次经验我梳理了一份从 fastjson 1.x 升级到 2.x 的标准操作流程SOP涵盖了从准备到上线的全过程。4.1 升级前准备风险评估与清单制定在动手改任何代码之前先做好以下准备依赖梳理 用mvn dependency:tree或 Gradle 的依赖分析工具精确找出项目中所有直接和间接依赖 fastjson 1.x 的地方。特别注意那些传递依赖可能有其他组件引入了老版本。API 使用情况扫描 使用代码搜索工具如 IDE 的全局搜索、grep查找所有import com.alibaba.fastjson的语句。统计JSON.parseObject、JSON.toJSONString、JSONArray、JSONObject、TypeReference、JSONField等关键 API 的使用点。这能帮你评估工作量。制定回滚方案 升级必须在可控的环境下进行。确保你有能力快速回滚到 fastjson 1.x 版本。这通常意味着要有清晰的发布流程和备份。建立测试基线 在升级前确保当前基于 fastjson 1.x 的测试套件全部通过。这个状态将作为后续对比的“金标准”。4.2 依赖变更与编译问题解决修改构建配置 在pom.xml或build.gradle中将 fastjson 依赖替换为 2.x。注意 groupId 从com.alibaba变为了com.alibaba.fastjson2。!-- Fastjson 2.x -- dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2/artifactId version2.0.9/version /dependency同时要使用exclusions排除所有传递依赖引入的 fastjson 1.x 版本避免冲突。处理编译错误 执行编译命令。常见的编译错误包括包路径错误 所有import com.alibaba.fastjson.*需要改为import com.alibaba.fastjson2.*。这是一个机械但量大的工作可以用 IDE 的批量重构功能。API 不兼容 fastjson 2.x 的 API 有大量重构。例如1.x 的SerializerFeature和ParseFeature在 2.x 中合并并重组为JSONReader.Feature和JSONWriter.Feature。需要根据编译错误信息查阅 fastjson2 官方文档 找到对应的新 API 或Feature。工具类缺失 一些 1.x 中的工具类如TypeUtils在 2.x 中可能被移除或改名。需要寻找替代方案或自己实现。4.3 运行时行为验证与兼容性测试编译通过只是第一步更重要的是保证运行时行为一致。单元测试修复 运行所有单元测试。失败的测试用例是宝贵的“行为差异探测器”。针对每个失败用例分析原因是因为字段名变了采用第3章的方案修复是因为null值处理方式变了调整Feature如JSONWriter.Feature.WriteNulls是因为日期格式变了使用JSONField(format“...”)或全局配置日期格式是因为自定义序列化器失效了重写 2.x 版本的ObjectWriter集成测试与 API 测试启动本地服务用 Postman 或 curl 调用关键接口对比升级前后的响应体。可以使用diff工具进行精确比对。如果项目有消费者驱动的契约测试如 Pact运行这些测试来验证接口契约未被破坏。特别关注涉及金额、身份证号等敏感数据的序列化确保精度和格式无误。性能与内存测试可选但建议 在测试环境进行压力测试对比升级前后的接口响应时间和 GC 情况。fastjson2 号称性能提升显著但需要在你自己的业务场景下验证。4.4 上线与监控灰度发布 不要全量一次性升级。可以先在少数不重要的服务或实例上部署观察日志和监控。加强监控 在上线后的一段时间内加强对相关服务错误日志、序列化异常告警的监控。可以针对性地增加一些健康检查接口专门测试核心 POJO 的序列化结果是否与预期一致。知识同步 将本次升级遇到的问题、解决方案和新的配置规范整理成文档同步给团队所有成员避免后续开发中再次踩坑。5. 常见问题排查清单与实战技巧下面是一个在升级过程中可能遇到的问题速查表以及我总结的一些实战技巧。问题现象可能原因排查步骤与解决方案字段名发生变化驼峰变小写等1. 默认命名策略差异 (CamelCase1xvsCamelCase)。2. Lombok等工具生成的Getter方法名特殊。1. 使用JSONField(name...)显式指定。2. 检查并统一字段命名风格。3. 尝试调整全局PropertyNamingStrategy需全面测试。字段缺失或新增了null字段Feature.WriteMapNullValue等控制字段是否输出的配置默认值改变。1. 检查全局和局部的Feature配置。2. 在toJSONString方法或HttpMessageConverter中明确指定所需的Feature。日期格式序列化结果不一致默认的日期格式 (DateFormat) 改变。1. 在字段上使用JSONField(formatyyyy-MM-dd HH:mm:ss)。2. 通过JSONWriter.Context配置全局日期格式。数字如BigDecimal精度或格式变化数字序列化的默认行为改变。1. 使用JSONField(serializeUsingMyNumberSerializer.class)自定义。2. 通过Feature.WriteBigDecimalAsPlain等控制输出格式。序列化/反序列化循环引用导致栈溢出1.x中默认开启的“循环引用检测”在2.x中可能默认关闭或配置方式不同。1. 检查Feature.DisableCircularReferenceDetect等相关配置。2. 在对象结构上避免循环引用或使用$ref表示。泛型类型反序列化失败TypeReference或Type的处理逻辑有变。1. 确保使用com.alibaba.fastjson2.TypeReference。2. 对于复杂泛型考虑使用JSON.parseObject(str, new TypeReference...(){})明确指定类型。自定义序列化器(ObjectSerializer)不生效2.x的自定义序列化器接口和注册方式已变。1. 实现2.x的ObjectWriter接口。2. 通过JSONFactory.getDefaultObjectWriterProvider().register(...)注册。与Spring Boot整合HttpMessageConverter配置失效未使用2.x对应的FastJson2HttpMessageConverter。1. 移除旧的FastJsonHttpMessageConverter配置。2. 添加并配置FastJson2HttpMessageConverter注意设置Features。实战技巧分享“双版本并存”测试法 在升级初期可以通过 Maven Shade 插件或自定义类加载器在测试环境中同时加载 fastjson 1.x 和 2.x 的类但使用不同的全限定名。编写一个测试工具对同一组数据分别用两个版本的 API 进行序列化并对比结果。这能最全面地发现行为差异。善用JSONWriter.Context和JSONReader.Context 这是 fastjson 2.x 的核心配置上下文。大部分全局行为如命名策略、日期格式、自定义序列化器注册、Feature开关都可以通过配置这两个Context来实现。在 Spring 项目中通常只需要配置一次FastJson2HttpMessageConverter时传入定制化的Context即可。关注JSONPath的使用 如果你的项目使用了 fastjson 的JSONPath功能进行 JSON 数据的查询和修改需要重点测试。2.x 的JSONPathAPI 可能有变动且在不同命名策略下路径表达式可能需要调整。漏洞扫描与 SafeMode 升级到 2.x 的一个重要目的是修复安全漏洞。确保了解 fastjson 2.x 的SafeMode特性。在反序列化不可信的 JSON 字符串时可以通过JSON.parseObject(str, clazz, JSONReader.Feature.SupportAutoType)来禁用自动类型识别AutoType这是防御反序列化攻击的关键。但注意SafeMode可能会影响某些依赖 AutoType 的功能。