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;@JsonIgnoreprivate 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 {@Overridepublic 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;@JsonCreatorpublic 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;}@JsonValuepublic 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;}@JsonValuepublic 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的官方文档以获取更多详细信息和高级用法。