Hi 👋, I'm shy 有人见尘埃，有人见星辰

---

Jackson常用注解详解

Jackson是Java生态系统中广泛使用的JSON处理库之一。它提供了一系列强大的注解，可以帮助我们更精确地控制Java对象与JSON之间的序列化和反序列化过程。本文将介绍一些常用的Jackson注解及其用法。

0. 引入依赖

<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/ -->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.17.2</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.17.2</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>2.17.2</version>
        </dependency>
        <!-- 支持xml格式 -->
		<dependency>
		    <groupId>com.fasterxml.jackson.dataformat</groupId>
		    <artifactId>jackson-dataformat-xml</artifactId>
		    <version>2.17.2</version>
		</dependency>

1. @JsonProperty

@JsonProperty注解用于指定Java字段与JSON属性之间的映射关系。

@Data
public class User {
    @JsonProperty("user_name")
    private String name;
}

在上面的例子中，Java对象的name字段将被序列化为JSON中的user_name属性。

2. @JsonIgnore

@JsonIgnore注解用于在序列化过程中忽略某个字段。

@Data
public class User {
    private String name;
    @JsonIgnore
    private String password;
}

在这个例子中，password字段将不会被包含在生成的JSON中。

3. @JsonFormat

@JsonFormat注解用于指定日期/时间字段的格式。

@Data
public class Event {
    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss")
    private Date timestamp;
}

这个注解将确保timestamp字段被格式化为指定的日期时间格式。

4. @JsonInclude

@JsonInclude注解用于指定在哪些情况下才将属性包含在JSON输出中。这个注解可以应用在类级别或字段级别。

以下是JsonInclude.Include枚举中所有可能的值，以及相应的代码示例：

@Data
public class User {
    // 1. ALWAYS：始终包含属性（默认行为）
    @JsonInclude(JsonInclude.Include.ALWAYS)
    private String alwaysIncluded = "always";
    // 2. NON_NULL：属性为非null时才包含
    @JsonInclude(JsonInclude.Include.NON_NULL)
    private String nonNull = null;
    // 3. NON_ABSENT：属性存在且非null时才包含（用于Optional字段）
    @JsonInclude(JsonInclude.Include.NON_ABSENT)
    private Optional<String> optionalField = Optional.empty();
    // 4. NON_EMPTY：属性非空时才包含（适用于集合、数组、字符串等）
    @JsonInclude(JsonInclude.Include.NON_EMPTY)
    private List<String> roles = new ArrayList<>();
    // 5. NON_DEFAULT：属性值为非默认值时才包含
    @JsonInclude(JsonInclude.Include.NON_DEFAULT)
    private int age = 0;
    // 6. CUSTOM：使用自定义的ValueFilter来决定是否包含属性
    @JsonInclude(value = JsonInclude.Include.CUSTOM, valueFilter = CustomFilter.class)
    private String customField = "";
    // 7. USE_DEFAULTS：使用默认的包含策略
    @JsonInclude(JsonInclude.Include.USE_DEFAULTS)
    private String useDefaults = "default";
}

// 自定义过滤器
public class CustomFilter {
    @Override
    public boolean equals(Object obj) {
        // 自定义过滤逻辑：只有当字段不为空字符串时才包含
        return obj == null || obj.toString().isEmpty();
    }
}

使用示例：

User user = new User();
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(user);
System.out.println(json);

输出结果如下：

5. @JsonCreator

@JsonCreator注解用于指定一个构造函数或工厂方法，Jackson将使用它来创建对象实例。这在处理不可变对象或需要特殊逻辑来创建对象时特别有用。

public class User {
    private final String name;
    private final int age;

    @JsonCreator
    public User(@JsonProperty("name") String name, @JsonProperty("age") int age) {
        this.name = name;
        this.age = age;
    }
}

在这个例子中，Jackson会使用这个带注解的构造函数来创建User对象，即使这些字段是final的。@JsonCreator通常与@JsonProperty配合使用，以确保JSON属性正确映射到构造函数参数。

6. @JsonValue

@JsonValue注解用于指定一个方法，该方法的返回值将被用作序列化整个对象的值。这在需要自定义对象的JSON表示时特别有用。

public class Color {
    private final String name;
    private final String hexValue;

    public Color(String name, String hexValue) {
        this.name = name;
        this.hexValue = hexValue;
    }

    @JsonValue
    public String getHexValue() {
        return hexValue;
    }
}

在这个例子中，当序列化Color对象时，JSON输出将只包含hexValue的值，而不是完整的对象结构。例如：

Color red = new Color("Red", "#FF0000");
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(red);
System.out.println(json); // 输出: "#FF0000"

@JsonValue注解也可以用于枚举类型，以自定义枚举值的序列化方式：

public enum Status {
    ACTIVE("A"),
    INACTIVE("I");

    private final String code;

    Status(String code) {
        this.code = code;
    }

    @JsonValue
    public String getCode() {
        return code;
    }
}

在这个例子中，Status枚举在序列化时将使用code值而不是枚举名称。

7. @JsonIgnoreProperties

@JsonIgnoreProperties注解用于指定一个或多个应该在序列化/反序列化过程中被忽略的属性。这个注解通常用在类级别。

@JsonIgnoreProperties({"password", "secretKey"})
public class User {
    private String username;
    private String password;  // 这个字段在JSON序列化时会被忽略
    private String secretKey;  // 这个字段在JSON序列化时会被忽略
}

它也可以用来忽略未知属性，这在处理来自外部系统的JSON数据时特别有用：

@JsonIgnoreProperties(ignoreUnknown = true)
public class User {
    private String username;
    private String email;
    // 如果JSON中包含了这个类中没有的属性，它们会被忽略而不会导致异常
}

结论

Jackson注解为我们提供了强大而灵活的工具，可以精确控制JSON序列化和反序列化的过程。通过合理使用这些注解，我们可以轻松处理各种复杂的JSON转换场景，提高代码的可读性和可维护性。

在实际应用中，可能还需要使用其他Jackson注解来满足特定需求。建议查阅Jackson的官方文档以获取更多详细信息和高级用法。