【若依(ruoyi)】fastjson升级2.x后PropertyPreFilters类缺失问题解析与解决方案

1. 问题背景与现象分析最近在升级若依(RuoYi)框架时遇到一个典型问题将fastjson从1.2.75升级到2.0.8版本后系统突然抛出NoClassDefFoundError: com/alibaba/fastjson/support/spring/PropertyPreFilters错误。这个错误让很多开发者措手不及特别是那些直接通过修改pom.xml版本号就以为能完成升级的同学。我刚开始也踩了这个坑。当时第一反应是检查maven依赖是否下载完整清理了本地仓库重新拉取依然报错。后来仔细对比文档才发现fastjson在2.x版本做了架构级调整。最直观的变化是包路径从com.alibaba.fastjson变成了com.alibaba.fastjson2而PropertyPreFilters这个在1.x版本常用的类在2.x中已经被重新设计。2. 错误根源深度解析2.1 fastjson版本差异的本质fastjson2并非简单的版本迭代而是近乎重构的新项目。官方文档明确说明fastjson 2.x是全新架构仅通过兼容层支持老版本。这意味着包结构变化所有核心类迁移到com.alibaba.fastjson2包下API调整许多1.x的类和方法被重新设计或废弃兼容策略通过fastjson-extension模块提供有限兼容2.2 PropertyPreFilters的演变在fastjson 1.x时代PropertyPreFilters是处理属性过滤的瑞士军刀。典型用法是这样的PropertyPreFilters filters new PropertyPreFilters(); PropertyPreFilters.MySimplePropertyPreFilter filter filters.addFilter(); filter.addExcludes(password,salt);但到了2.x版本这个类被拆解为更精细的过滤组件。新版本推荐使用SimplePropertyPreFilter其使用方式更符合单一职责原则SimplePropertyPreFilter filter new SimplePropertyPreFilter(); filter.getExcludes().add(password); filter.getExcludes().add(salt);3. 完整解决方案3.1 依赖配置调整首先确保pom.xml使用正确的依赖坐标。注意fastjson2的groupId已经变更!-- 错误写法沿用旧坐标 -- dependency groupIdcom.alibaba/groupId artifactIdfastjson/artifactId version2.0.8/version /dependency !-- 正确写法 -- dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2/artifactId version2.0.8/version /dependency !-- 如果需要兼容层 -- dependency groupIdcom.alibaba.fastjson2/groupId artifactIdfastjson2-extension/artifactId version2.0.8/version /dependency3.2 代码改造方案针对原始代码中的setRequestValue方法需要做如下改造// 改造前fastjson 1.x写法 private void setRequestValue(SysOperLog operLog) throws Exception { MapString, String[] map ServletUtils.getRequest().getParameterMap(); if (StringUtils.isNotEmpty(map)) { PropertyPreFilters.MySimplePropertyPreFilter excludefilter new PropertyPreFilters().addFilter(); excludefilter.addExcludes(EXCLUDE_PROPERTIES); String params JSONObject.toJSONString(map, excludefilter); operLog.setOperParam(StringUtils.substring(params, 0, 2000)); } } // 改造后fastjson 2.x写法 private void setRequestValue(SysOperLog operLog) throws Exception { MapString, String[] map ServletUtils.getRequest().getParameterMap(); if (StringUtils.isNotEmpty(map)) { SimplePropertyPreFilter serializeFilter new SimplePropertyPreFilter(); serializeFilter.getExcludes().addAll(Arrays.asList(EXCLUDE_PROPERTIES)); String params JSONObject.toJSONString(map, serializeFilter); operLog.setOperParam(StringUtils.substring(params, 0, 2000)); } }3.3 兼容性处理技巧如果项目中有大量旧代码难以立即改造可以临时使用兼容方案添加fastjson2的extension模块在启动类添加兼容配置Bean public JSON json() { JSONFactory.setUseJacksonAnnotation(false); return new JSON(); }4. 升级后的验证与测试完成改造后建议进行以下验证基础功能测试检查所有原先使用fastjson的接口是否正常性能对比使用JMeter等工具对比序列化/反序列化性能内存监控观察升级后内存使用情况fastjson2在某些场景下内存占用更低我在实际项目中验证发现同样的数据序列化fastjson2比1.x版本快约30%特别是在处理大JSON时效果更明显。不过要注意的是2.x版本对循环引用的处理策略有所变化需要检查相关业务逻辑是否受影响。5. 常见问题排查指南5.1 类找不到问题如果遇到其他类找不到的情况可以参考这个对照表1.x 类路径2.x 替代方案com.alibaba.fastjson.JSONcom.alibaba.fastjson2.JSONcom.alibaba.fastjson.serializer.SerializerFeaturecom.alibaba.fastjson2.JSONWriter.Featurecom.alibaba.fastjson.parser.Featurecom.alibaba.fastjson2.JSONReader.Feature5.2 序列化差异处理fastjson2对日期格式的处理更严格建议显式指定格式// 旧写法 JSON.toJSONString(obj); // 新写法推荐 JSON.toJSONString(obj, JSONWriter.Feature.WriteDateUseDateFormat, JSONWriter.Feature.PrettyFormat);6. 最佳实践建议经过多个项目的升级实践我总结出以下经验渐进式升级先在新模块使用fastjson2逐步改造旧代码统一配置创建JsonUtils工具类封装常用操作注解迁移将JSONField等注解的包路径改为fastjson2测试覆盖重点测试包含复杂对象图的场景特别提醒若依框架中与权限相关的接口往往涉及敏感字段过滤升级后务必重点测试这些接口的返回值过滤是否生效。