Jackson ObjectMapper序列化时如何忽略空字段？

Question

在使用 Jackson 的 `ObjectMapper` 进行对象序列化为 JSON 的过程中，经常会遇到需要**忽略空字段**（如 null、空字符串、空数组等）的场景，以减少 JSON 输出体积或满足接口规范。那么，如何配置 `ObjectMapper` 使其在序列化时自动忽略这些空值字段？常见的做法是通过设置 `SerializationFeature` 和 `setSerializationInclusion` 方法，但开发者常常对其具体用法和不同参数的效果不够清晰，导致配置无效或结果不符合预期。此外，不同版本的 Jackson 在处理空字段时的行为也可能存在差异。因此，如何正确配置 `ObjectMapper` 以实现精准的空字段过滤，是一个值得深入探讨的技术问题。

Answer 1

一、引言：Jackson 序列化中忽略空字段的必要性

在现代 Web 开发中，Jackson 是 Java 领域最常用的 JSON 处理库之一。其中 ObjectMapper 作为核心类，负责 Java 对象与 JSON 字符串之间的相互转换。在实际开发中，我们常常希望在序列化过程中忽略空字段（如 null、空字符串、空数组等），以减少 JSON 数据体积、提升接口响应性能，或满足接口规范。

然而，开发者在使用 Jackson 的 setSerializationInclusion 和 SerializationFeature 等配置时，常常对其作用机制理解不清，导致配置无效或结果不符合预期。

二、基础配置：使用 setSerializationInclusion 忽略空字段

最常见且推荐的做法是通过 ObjectMapper.setSerializationInclusion() 方法设置序列化时字段的包含策略。该方法接受一个 JsonInclude.Include 枚举参数。

ObjectMapper mapper = new ObjectMapper();
mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);

• JsonInclude.Include.NON_NULL：忽略值为 null 的字段。
• JsonInclude.Include.NON_EMPTY：忽略 null、空字符串（""）、空数组、空对象等。
• JsonInclude.Include.NON_DEFAULT：忽略默认值字段（如数字类型为 0、布尔值为 false 等）。

例如，当字段值为 null 或空字符串时，若设置为 NON_EMPTY，该字段将不会出现在最终的 JSON 输出中。

三、进阶配置：结合 SerializationFeature 控制序列化行为

除了字段级别的过滤策略，还可以通过 ObjectMapper.enable() 或 disable() 方法启用或禁用特定的序列化特性。

ObjectMapper mapper = new ObjectMapper();
mapper.enable(SerializationFeature.INDENT_OUTPUT); // 启用美化输出
mapper.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS); // 忽略空对象异常

虽然 SerializationFeature 不直接控制字段是否序列化，但某些特性会影响序列化过程的行为，例如是否抛出异常，或是否输出空对象。

四、版本差异：不同 Jackson 版本对空字段处理的异同

不同版本的 Jackson 在处理空字段时存在行为差异，尤其在 NON_EMPTY 的语义上：

Jackson 版本	NON_EMPTY 行为说明
v2.9.x 及以下	仅忽略 null 和空集合，对空字符串不生效
v2.10+ 及以上	支持忽略 null、空字符串、空数组、空对象等

因此，在升级 Jackson 版本后，建议重新测试空字段的过滤逻辑是否符合预期。

五、注解控制：在类或字段上使用 @JsonInclude 细粒度控制

除了全局配置，Jackson 还支持在类或字段级别使用 @JsonInclude 注解，实现更细粒度的控制。

@Data
@JsonInclude(JsonInclude.Include.NON_EMPTY)
public class User {
    private String name;
    private Integer age;
    private List hobbies;
}

上述代码中，所有字段都遵循 NON_EMPTY 规则进行过滤。也可以对个别字段单独指定：

public class User {
    @JsonInclude(JsonInclude.Include.NON_NULL)
    private String name;

    @JsonInclude(JsonInclude.Include.NON_DEFAULT)
    private Integer age;
}

六、自定义过滤器：实现 BeanPropertyWriter 或 PropertyFilter

对于更复杂的空值判断逻辑，可以实现自定义的属性过滤器。例如，使用 SimpleBeanPropertyFilter 和 FilterProvider：

SimpleBeanPropertyFilter filter = SimpleBeanPropertyFilter.serializeAllExcept("emptyField");
FilterProvider filters = new SimpleFilterProvider().addFilter("customFilter", filter);
ObjectMapper mapper = new ObjectMapper();
mapper.setFilterProvider(filters);

也可以通过继承 BeanPropertyWriter 实现更灵活的字段过滤逻辑，适用于需要动态判断字段是否为空的场景。

七、实战建议与注意事项

在实际项目中，建议遵循以下原则：

• 优先使用 setSerializationInclusion(JsonInclude.Include.NON_EMPTY) 作为全局配置。
• 针对特定类或字段使用 @JsonInclude 实现局部控制。
• 注意 Jackson 不同版本间的兼容性问题，尤其是 NON_EMPTY 的语义变化。
• 对于复杂业务逻辑，考虑使用自定义过滤器。

此外，测试环节必须包含空字段的序列化输出验证，避免因配置不当导致接口数据异常。