深入理解 Jackson 序列化注解@JsonInclude、@JsonIgnore、@JsonFormat、@JsonSerialize、@JsonIgnoreProperties、@JsonIgn

在使用 Java 进行开发时，处理 JSON 数据是一个非常常见的需求。而 Jackson 是最受欢迎的 Java JSON 序列化/反序列化库之一。Jackson 提供了一系列注解，帮助开发者控制如何将 Java 对象转换为 JSON，以及如何将 JSON 反序列化为 Java 对象。在本文中，我们将探讨几个常见的 Jackson 注解，分别是 @JsonInclude、@JsonIgnore、@JsonFormat、@JsonSerialize、@JsonIgnoreProperties 和 @JsonIgnoreType，并介绍它们的使用方法与区别

1. @JsonInclude

@JsonInclude 控制字段在序列化时是否包含到 JSON 中。它允许我们根据特定条件排除值，例如 null 或空值。常见的策略包括排除 null 值、空集合、空字符串等。

常见用法：

• JsonInclude.Include.NON_NULL: 排除 null 值。
• JsonInclude.Include.NON_EMPTY: 排除 null 或空值（例如空集合、空字符串）。
• JsonInclude.Include.NON_DEFAULT: 排除字段的默认值。

示例：

public class User {
    private String username;

    @JsonInclude(JsonInclude.Include.NON_NULL)
    private String email;

    @JsonInclude(JsonInclude.Include.NON_EMPTY)
    private List<String> roles = new ArrayList<>();

    // Getters and Setters
}

说明：

• 当 email 为 null 时，序列化 JSON 时会被忽略。
• 当 roles 为空列表时，序列化时不会包含在 JSON 中。

2. @JsonIgnore

@JsonIgnore 用于在序列化和反序列化时忽略特定字段。不管是序列化还是反序列化，该注解标记的字段都不会被处理。

示例：

public class User {
    private String username;

    @JsonIgnore
    private String password;

    // Getters and Setters
}

说明：

• password 字段不会被序列化到 JSON 中，也不会在反序列化时从 JSON 中读取这个字段的值。

3. @JsonFormat

@JsonFormat 用于定义字段在序列化和反序列化时的格式化方式，最常用于日期或时间字段。它可以指定日期的格式、时区等。

示例：

public class Event {
    private String name;

    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date eventDate;

    // Getters and Setters
}

说明：

• eventDate 字段在序列化时会以 yyyy-MM-dd HH:mm:ss 格式显示，并使用 GMT+8 时区。
• 反序列化时也会按照该格式解析日期。

4. @JsonSerialize

@JsonSerialize 用于指定自定义的序列化器。对于某些复杂类型或自定义的序列化逻辑，我们可以使用此注解，结合自定义的序列化类。

示例：

public class User {
    private String name;

    @JsonSerialize(using = CustomPasswordSerializer.class)
    private String password;

    // Getters and Setters
}

 自定义序列化器：

public class CustomPasswordSerializer extends JsonSerializer<String> {
    @Override
    public void serialize(String value, JsonGenerator gen, SerializerProvider serializers) throws IOException {
        gen.writeString("****"); // 将密码序列化为 "****"
    }
}

说明：

• 在序列化 password 字段时，会使用 CustomPasswordSerializer，将密码替换为 ****

5. @JsonIgnoreProperties

@JsonIgnoreProperties 用于指定类级别的属性忽略规则。它允许我们在类上定义多个字段，这些字段将被忽略，不会被序列化或反序列化。

示例：

@JsonIgnoreProperties({ "password", "email" })
public class User {
    private String username;
    private String password;
    private String email;

    // Getters and Setters
}

说明：

• password 和 email 字段会被忽略，既不会出现在 JSON 中，也不会在反序列化时读取这些字段。

6. @JsonIgnoreType

@JsonIgnoreType 用于忽略某个类的所有实例。通常用于嵌套对象的忽略，所有该类型的字段都会被忽略。

示例：

@JsonIgnoreType
public class Address {
    private String street;
    private String city;
    // Getters and Setters
}

public class User {
    private String username;
    private Address address;

    // Getters and Setters
}

说明：

• Address 类及其实例将会完全被忽略，序列化和反序列化时不会处理 address 字段。

各注解的区别与使用场景总结