|------------------------------------|----------------------------------------------------------------------------------------|
| ## Hi 👋, I'm shy #### 有人见尘埃,有人见星辰 | |
Jackson常用注解详解
文章目录
- Jackson常用注解详解
-
- [0. 引入依赖](#0. 引入依赖)
- [1. @JsonProperty](#1. @JsonProperty)
- [2. @JsonIgnore](#2. @JsonIgnore)
- [3. @JsonFormat](#3. @JsonFormat)
- [4. @JsonInclude](#4. @JsonInclude)
- [5. @JsonCreator](#5. @JsonCreator)
- [6. @JsonValue](#6. @JsonValue)
- [7. @JsonIgnoreProperties](#7. @JsonIgnoreProperties)
- 结论
Jackson是Java生态系统中广泛使用的JSON处理库之一。它提供了一系列强大的注解,可以帮助我们更精确地控制Java对象与JSON之间的序列化和反序列化过程。本文将介绍一些常用的Jackson注解及其用法。
0. 引入依赖
xml
<!-- 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属性之间的映射关系。
java
@Data
public class User {
@JsonProperty("user_name")
private String name;
}
在上面的例子中,Java对象的name
字段将被序列化为JSON中的user_name
属性。
2. @JsonIgnore
@JsonIgnore
注解用于在序列化过程中忽略某个字段。
java
@Data
public class User {
private String name;
@JsonIgnore
private String password;
}
在这个例子中,password
字段将不会被包含在生成的JSON中。
3. @JsonFormat
@JsonFormat
注解用于指定日期/时间字段的格式。
java
@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
枚举中所有可能的值,以及相应的代码示例:
java
@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();
}
}
使用示例:
java
User user = new User();
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(user);
System.out.println(json);
输出结果如下:
5. @JsonCreator
@JsonCreator
注解用于指定一个构造函数或工厂方法,Jackson将使用它来创建对象实例。这在处理不可变对象或需要特殊逻辑来创建对象时特别有用。
java
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表示时特别有用。
java
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
的值,而不是完整的对象结构。例如:
java
Color red = new Color("Red", "#FF0000");
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(red);
System.out.println(json); // 输出: "#FF0000"
@JsonValue
注解也可以用于枚举类型,以自定义枚举值的序列化方式:
java
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
注解用于指定一个或多个应该在序列化/反序列化过程中被忽略的属性。这个注解通常用在类级别。
java
@JsonIgnoreProperties({"password", "secretKey"})
public class User {
private String username;
private String password; // 这个字段在JSON序列化时会被忽略
private String secretKey; // 这个字段在JSON序列化时会被忽略
}
它也可以用来忽略未知属性,这在处理来自外部系统的JSON数据时特别有用:
java
@JsonIgnoreProperties(ignoreUnknown = true)
public class User {
private String username;
private String email;
// 如果JSON中包含了这个类中没有的属性,它们会被忽略而不会导致异常
}
结论
Jackson注解为我们提供了强大而灵活的工具,可以精确控制JSON序列化和反序列化的过程。通过合理使用这些注解,我们可以轻松处理各种复杂的JSON转换场景,提高代码的可读性和可维护性。
在实际应用中,可能还需要使用其他Jackson注解来满足特定需求。建议查阅Jackson的官方文档以获取更多详细信息和高级用法。