了！Fastjson实战中这几个坑你踩过吗？（附避坑指南）)
Fastjson高阶避坑指南：从类型擦除到自定义序列化的深度实践
如果你还在用JSONObject.parseObject()处理所有JSON转换需求，那这篇文章可能会颠覆你的认知。上周我们团队刚解决了一个线上事故——因为Fastjson默认配置导致的日期格式不一致问题，让三个微服务之间的数据交互彻底瘫痪了4小时。这不是我第一次见到Fastjson引发的生产事故，但每次排查都让我对这个"简单"的JSON库产生新的敬畏。
1. 泛型处理的类型擦除陷阱
当你在Controller层写下List<User> users = JSON.parseObject(jsonStr, List.class)时，灾难的种子已经埋下。Fastjson在处理泛型时会遭遇Java的类型擦除机制，这导致反序列化后的集合元素全部变成JSONObject而非你期望的User对象。
典型问题重现：
String json = "[{\"name\":\"张三\"},{\"name\":\"李四\"}]"; List<User> users = JSON.parseObject(json, List.class); // 运行时抛出ClassCastException User firstUser = users.get(0);正确解决方案：
// 方案1：使用TypeReference保留泛型信息 List<User> users = JSON.parseObject(json, new TypeReference<List<User>>(){}); // 方案2：Java 8+的便捷写法 List<User> users = JSON.parseArray(json, User.class);注意：当处理多层嵌套泛型时（如Map<String, List<User>>），必须使用TypeReference。我们在订单系统中就遇到过将Map<String, List<OrderItem>>反序列化为Map<String, List<JSONObject>>导致业务逻辑异常的案例。
2. 循环引用与$ref的相爱相杀
对象间的双向关联是业务建模的常见需求，但直接序列化会导致堆栈溢出。Fastjson默认启用循环引用检测后会生成$ref引用标记，这虽然解决了溢出问题，却可能引发其他兼容性问题。
循环引用示例：
class Department { private List<Employee> employees; } class Employee { private Department department; } Department dept = new Department(); Employee emp = new Employee(); dept.setEmployees(Arrays.asList(emp)); emp.setDepartment(dept); String json = JSON.toJSONString(dept); // 输出结果包含$ref： // {"employees":[{"department":{"$ref":"$"}}]}应对策略对比：
| 场景 | 推荐配置 | 优缺点 |
|---|---|---|
| 纯Fastjson环境 | SerializerFeature.DisableCircularReferenceDetect | 避免$ref但需控制序列化深度 |
| 多系统交互 | 自定义SerializeFilter | 可精细控制但实现复杂 |
| 前端展示需求 | 使用DTO剥离关联 | 结构清晰但增加转换成本 |
我们在用户权限系统中采用的自定义方案：
JSON.toJSONString(dept, SerializerFeature.DisableCircularReferenceDetect, SerializerFeature.WriteMapNullValue);3. 日期格式的暗礁区
Fastjson的日期处理堪称"配置地狱"，不同版本间的默认行为差异足以让人崩溃。我们曾因测试环境(1.2.54)和生产环境(1.2.83)版本不同导致日期格式不兼容，引发批量任务失败。
关键配置矩阵：
// 全局配置（推荐初始化时设置） JSON.DEFFAULT_DATE_FORMAT = "yyyy-MM-dd HH:mm:ss"; // 单次序列化指定格式 String json = JSON.toJSONString(bean, SerializerFeature.WriteDateUseDateFormat); // 反序列化时指定格式 Model obj = JSON.parseObject(json, Model.class, Feature.AllowISO8601DateFormat);日期处理的最佳实践：
- 所有微服务统一Fastjson版本
- 显式声明
@JSONField(format="yyyy-MM-dd")注解 - 跨系统传输时使用时间戳(long)而非格式字符串
- 时区敏感场景强制指定
TimeZone.getTimeZone("GMT+8")
4. 特殊字符的转义战争
当JSON字符串包含换行符、emoji或HTML标签时，默认的转义行为可能导致可读性灾难。某次我们处理用户输入的富文本内容时，发现序列化后的JSON几乎不可读。
转义控制方案：
// 禁用自动转义（谨慎使用） JSON.DEFAULT_GENERATE_FEATURE |= SerializerFeature.DisableCheckSpecialChar.getMask(); // 自定义转义处理器 SerializeWriter out = new SerializeWriter(); out.config(SerializerFeature.DisableCheckSpecialChar, true); JSONSerializer serializer = new JSONSerializer(out); serializer.write(content); String result = out.toString();真实案例：处理包含XML片段的JSON时，我们最终采用BASE64编码方案：
@JSONField(serializeUsing = Base64Serializer.class) private String xmlContent;5. 版本升级的兼容性雷区
从1.2.x升级到2.x版本是个充满陷阱的过程。我们花了两个月逐步迁移，总结出这些经验：
重大变更应对表：
| 旧版本行为 | 新版本变化 | 迁移方案 |
|---|---|---|
| 自动识别单引号 | 严格双引号 | 预处理替换字符 |
| 宽松类型转换 | 严格类型检查 | 添加Feature.AllowArbitraryCommas |
| 默认关闭ASM | 默认启用ASM | 测试序列化性能差异 |
| 无安全模式 | 新增autoTypeFilter | 白名单配置 |
安全配置示例：
# fastjson2安全配置 fastjson2.parser.autoTypeAccept=com.ourpackage. fastjson2.parser.deny=org.apache.commons.collections4.6. 性能调优的隐藏参数
在大数据量处理场景下，这些配置可能带来5-10倍的性能提升：
// 初始化时配置（单例模式） static { // 启用ASM字节码增强 ParserConfig.getGlobalInstance().setAsmEnable(true); // 缓存反序列化器 ParserConfig.getGlobalInstance().setAutoTypeSupport(true); // 预编译复杂对象的序列化器 SerializeConfig.getGlobalInstance().put(BigDecimal.class, new BigDecimalCodec()); } // 高频调用场景专用API String json = JSON.toJSONString( data, SerializeConfig.getGlobalInstance(), SerializerFeature.WriteNonStringValueAsString, SerializerFeature.IgnoreNonFieldGetter );性能对比数据（处理10万条订单数据）：
| 配置组合 | 耗时(ms) | 内存峰值(MB) |
|---|---|---|
| 默认参数 | 1450 | 320 |
| ASM+缓存 | 280 | 110 |
| 预编译序列化器 | 190 | 90 |
7. 自定义序列化的高阶玩法
当标准序列化不能满足需求时，Fastjson的扩展接口展现出强大灵活性。这是我们为金融系统设计的金额格式化方案：
public class MoneySerializer implements ObjectSerializer { @Override public void write( JSONSerializer serializer, Object object, Object fieldName, Type fieldType, int features) throws IOException { BigDecimal value = (BigDecimal) object; String formatted = value.setScale(2, RoundingMode.HALF_UP) .stripTrailingZeros() .toPlainString(); serializer.write(formatted); } } // 注册自定义序列化器 SerializeConfig.getGlobalInstance().put(BigDecimal.class, new MoneySerializer());扩展应用场景：
- 敏感数据脱敏
- 枚举值特殊处理
- 第三方类库适配
- 二进制字段编码
在监控系统中，我们通过自定义序列化器实现了指标数据的压缩传输：
public class MetricSerializer implements ObjectSerializer { public void write(...) { MetricData data = (MetricData) object; byte[] compressed = Snappy.compress(data.toBytes()); serializer.write(Base64.getEncoder().encodeToString(compressed)); } }
