Hi 👋, I'm shy有人见尘埃,有人见星辰 | ![]() |
Jackson常用注解详解
文章目录
- Jackson常用注解详解
- 0. 引入依赖
- 1. @JsonProperty
- 2. @JsonIgnore
- 3. @JsonFormat
- 4. @JsonInclude
- 5. @JsonCreator
- 6. @JsonValue
- 7. @JsonIgnoreProperties
- 结论
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的官方文档以获取更多详细信息和高级用法。