@JsonInclude 基于属性值的包含规则

@JsonInclude 可用于指示何时可以对被注解的属性值进行序列化。通常会序列化所有的属性值，但是通过使用此注解，我们可以基于属性值指定简单的排除规则。

@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.FIELD,
    ElementType.TYPE, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonInclude
{
    public Include value() default Include.ALWAYS;// 属性的包含规则

    public Include content() default Include.ALWAYS;// 元素的包含规则（只应用于元素，不用于字段本身），Map 或 AtomicReference，Map 是对 value 判断（不是 key），AtomicReference 是对 get() 方法的返回值进行判断

    public Class<?> valueFilter() default Void.class;// Include.CUSTOM 时的自定义过滤器

    public Class<?> contentFilter() default Void.class;// Include.CUSTOM 时的自定义过滤器
    
    public enum Include
    {
        ALWAYS,// 始终包含

        NON_NULL,// 不包含 null

        NON_ABSENT,// 不包含 null；不包含 absent 值（比如引用 null 的 Optional、 AtomicReference）

        NON_EMPTY,// NON_NULL + NON_ABSENT; isEmpty() 返回 true的 Collections、Map；length==0 的 arrays；length() 返回 0 的 String

        NON_DEFAULT,// NON_EMPTY；基本类型及其包装类型的默认值；毫秒为 0L 的日期、时间；当用于类级别时，会用无参构造方法创建一个实例，然后用equals()方法比较每个字段，返回true时会排除这个字段。

        CUSTOM,// 需要用valueFilter()或contentFilter()指定自定义的过滤器

        USE_DEFAULTS// 使用更高级别的默认值。如果用于属性上，则将使用类级别设置（如果存在），否则将使用全局的规则（由ObjectMapper设置）。
        ;
    }
}

Example

Java Object

@JsonInclude(JsonInclude.Include.NON_NULL)
public class Employee {
    private String name;
    private String dept;
    private String address;
    ...
}    

Main class

public class ExampleMain {
    public static void main(String[] args) throws IOException {
        Employee employee = Employee.of("Trish", null, null);
        ObjectMapper om = new ObjectMapper();
        String jsonString = om.writeValueAsString(employee);
        System.out.println(jsonString);
    }
}

输出只包含 name，因为 dept、address 都为 null。

{"name":"Trish"}

不使用 @JsonInclude

{"name":"Trish","dept":null,"address":null}

全局设置

ObjectMapper#setDefaultPropertyInclusion() 可以指定全局的属性包含规则：

public class Employee {
    private String name;
    private String dept;
    private String address;
    ...
}    

public class ExampleMain2 {
    public static void main(String[] args) throws IOException {
        Employee employee = Employee.of("Trish", null, null);
        
        ObjectMapper om = new ObjectMapper();
        om.setDefaultPropertyInclusion(JsonInclude.Include.NON_NULL);

        String jsonString = om.writeValueAsString(employee);
        System.out.println(jsonString);
    }
}

原文链接

1. Jackson JSON - Using @JsonInclude to define properties inclusion rules
2. Jackson JSON - @JsonInclude NON_ABSENT Example
3. Jackson JSON - @JsonInclude NON_EMPTY Example
4. Jackson JSON - @JsonInclude NON_DEFAULT Example
5. Jackson JSON - @JsonInclude USE_DEFAULTS Example
6. Jackson JSON - Using content attribute of @JsonInclude to apply include rules for Map entries and content of referential type