当前位置：首页 > news >正文

fastjson2避坑指南：为什么你的null值字段不显示？

news 2026/8/23 1:47:02

Fastjson2实战避坑：为什么你的null值字段神秘消失了？

最近在重构一个老项目时，我遇到了一个令人抓狂的问题——明明数据库查询返回的对象中有null值字段，但经过fastjson2序列化后，这些字段就像人间蒸发了一样。这直接导致前端同事频繁报错，因为某些字段在特定场景下必须存在，即使值为null。如果你也在fastjson2中遇到过类似的"灵异事件"，不妨跟着我一起揭开这个谜团。

1. 问题重现：当null值遇上fastjson2

让我们从一个简单的例子开始。假设我们有一个用户信息类：

public class User { private String name; private Integer age; private List<String> hobbies; // 省略getter/setter }

当我们将一个部分字段为null的对象序列化为JSON时：

User user = new User(); user.setName("张三"); // age和hobbies保持null System.out.println(JSON.toJSONString(user));

在fastjson1中，输出会是：

{"age":null,"hobbies":null,"name":"张三"}

但在fastjson2中，你可能会惊讶地看到：

{"name":"张三"}

注意：这不是bug，而是fastjson2的默认行为设计。理解这一点是解决问题的关键。

2. 根源分析：fastjson2的默认行为变革

fastjson2作为fastjson的重大升级版本，在性能优化的同时，也调整了一些默认行为：

空间效率优先：fastjson2默认不序列化null值字段，以减少网络传输数据量
安全考虑：避免暴露不必要的字段信息
性能优化：跳过null值检查可以提升约15%的序列化速度

这种改变虽然合理，但却让从fastjson1迁移过来的开发者措手不及。下表对比了两个版本的关键差异：

特性	fastjson1	fastjson2
默认序列化null字段	是	否
性能	较慢	快15%-300%
安全机制	基础	增强
内存占用	较高	较低

3. 解决方案：四招让你的null值重见天日

3.1 全局配置法（推荐用于新项目）

如果你希望在整个应用中保持一致的null值序列化行为，可以在应用启动时配置全局默认参数：

JSON.config(JSONWriter.Feature.WriteMapNullValue);

这样配置后，所有通过JSON.toJSONString()的序列化操作都会包含null值字段。

适用场景：

全新项目
需要统一序列化风格
前端强烈依赖字段存在性（即使为null）

3.2 单次序列化配置（灵活控制）

对于需要精细控制的场景，可以在每次序列化时指定特性：

JSON.toJSONString(user, JSONWriter.Feature.WriteMapNullValue);

如果需要更细致的控制，还可以组合多个特性：

JSON.toJSONString(user, new JSONWriter.Feature[] { JSONWriter.Feature.WriteMapNullValue, JSONWriter.Feature.WriteNullListAsEmpty, JSONWriter.Feature.WriteNullStringAsEmpty });

特性组合说明：

WriteMapNullValue：输出Map中的null值
WriteNullListAsEmpty：将null列表输出为[]
WriteNullStringAsEmpty：将null字符串输出为""

3.3 注解驱动法（精准控制）

如果你只想对特定类的特定字段进行控制，可以使用@JSONField注解：

public class User { private String name; @JSONField(serializeFeatures = JSONWriter.Feature.WriteMapNullValue) private Integer age; @JSONField(serializeFeatures = JSONWriter.Feature.WriteNullListAsEmpty) private List<String> hobbies; }

这种方法特别适合：

大型项目中的特定领域模型
需要与旧API保持兼容的情况
某些字段必须存在而其他字段可以忽略的场景

3.4 自定义序列化器（终极解决方案）

对于极其复杂的场景，你可以实现自定义的序列化器：

public class NullValueSerializer implements ObjectSerializer { @Override public void write(JSONWriter writer, Object object, Object fieldName, Type fieldType, long features) { if (object == null) { writer.writeNull(); } else { writer.writeAny(object); } } } // 注册自定义序列化器 JSON.register(User.class, new NullValueSerializer());

适用场景：

需要特殊null值处理逻辑
统一处理某种类型的null值
实现完全自定义的序列化策略

4. 深入原理：fastjson2是如何处理null值的

要真正掌握null值处理，我们需要理解fastjson2的内部机制：

字段扫描阶段：
- 通过反射获取所有字段
- 检查字段值是否为null
- 根据配置决定是否跳过

序列化决策树：

graph TD A[开始序列化] --> B{字段值为null?} B -->|是| C{启用WriteMapNullValue?} C -->|是| D[序列化字段名和null值] C -->|否| E[跳过该字段] B -->|否| F[正常序列化字段]

性能优化点：
- 字段缓存减少反射开销
- 提前判断跳过null值检查
- 基于ASM的动态代码生成

5. 实战建议：如何选择最佳方案

根据不同的项目阶段和需求，我推荐以下策略：

新项目启动：

在项目初期明确null值处理规范
统一使用全局配置或注解方式
在API文档中明确说明null值处理方式

老项目迁移：

首先评估现有API对null值的依赖程度
逐步替换fastjson1的调用点
添加单元测试确保行为一致
使用注解方式处理特殊case

微服务架构：

在API网关层统一处理null值
为不同服务配置不同的序列化策略
使用DTO而非直接序列化领域模型

6. 避坑锦囊：你可能遇到的其它null值问题

除了基本的null值字段显示问题，在实际开发中还会遇到一些变种情况：

集合类型null值：

// 默认情况下，null列表会被忽略 List<String> nullList = null; System.out.println(JSON.toJSONString(nullList)); // 输出为null // 使用WriteNullListAsEmpty特性 System.out.println(JSON.toJSONString(nullList, JSONWriter.Feature.WriteNullListAsEmpty)); // 输出为[]

Map中的null值：

Map<String, Object> map = new HashMap<>(); map.put("key1", null); map.put("key2", "value"); // 默认输出：{"key2":"value"} // 使用WriteMapNullValue后：{"key1":null,"key2":"value"}

日期格式化中的null值：

public class Event { @JSONField(format = "yyyy-MM-dd") private Date eventDate; } Event event = new Event(); // eventDate为null // 默认输出：{} // 使用WriteMapNullValue后：{"eventDate":null}