Jackson高级注解详解

1. 概述

本文介绍了一些Jackson的高级注解。

2. @JsonIdentityReference

@JsonIdentityReference 用于自定义对将被序列化为对象标识而不是完整 POJO 的对象的引用。它与*@JsonIdentityInfo合作，强制在每个序列化中使用对象标识，这与@JsonIdentityInfo*不存在时的情形不同。这两个注解在处理对象之间的循环依赖关系时最有帮助。

为了演示使用*@JsonIdentityReference*，我们将定义两个不同的bean类，一个没有这个注解，一个有这个注解。

没有*@JsonIdentityReference*的bean:

@JsonIdentityInfo(generator = ObjectIdGenerators.PropertyGenerator.class, property = "id")
public class BeanWithoutIdentityReference {
private int id;
private String name;
// constructor, getters and setters
}

对于使用*@JsonIdentityReference的bean，我们选择id*属性作为对象标识:

@JsonIdentityInfo(generator = ObjectIdGenerators.PropertyGenerator.class, property = "id")
@JsonIdentityReference(alwaysAsId = true)
public class BeanWithIdentityReference {
private int id;
private String name;
// constructor, getters and setters
}

在第一种情况下，@JsonIdentityReference不存在，该bean被序列化，包含其属性的完整细节:

BeanWithoutIdentityReference bean
= new BeanWithoutIdentityReference(1, "Bean Without Identity Reference Annotation");
String jsonString = mapper.writeValueAsString(bean);

上面序列化的输出:

{
"id": 1,
"name": "Bean Without Identity Reference Annotation"
}

当使用*@JsonIdentityReference*时，bean被序列化为一个简单的标识:

BeanWithIdentityReference bean
= new BeanWithIdentityReference(1, "Bean With Identity Reference Annotation");
String jsonString = mapper.writeValueAsString(bean);
assertEquals("1", jsonString);

3. @JsonAppend

@JsonAppend注解用于在序列化对象时向对象添加虚拟属性，而不是常规属性。当我们希望直接向JSON字符串中添加补充信息而不是更改类定义时，这是必要的。例如，将bean的version元数据插入到相应的JSON文档中可能比为其提供额外的属性更方便。

假设我们有一个没有*@JsonAppend*的bean，如下所示:

public class BeanWithoutAppend {
private int id;
private String name;
// constructor, getters and setters
}

测试将确认，在没有*@JsonAppend注解的情况下，序列化输出不包含关于补充version属性的信息，尽管我们试图添加到ObjectWriter*对象:

BeanWithoutAppend bean = new BeanWithoutAppend(2, "Bean Without Append Annotation");
ObjectWriter writer
= mapper.writerFor(BeanWithoutAppend.class).withAttribute("version", "1.0");
String jsonString = writer.writeValueAsString(bean);

序列化输出:

{
"id": 2,
"name": "Bean Without Append Annotation"
}

现在，假设我们有一个用*@JsonAppend*注解的bean:

@JsonAppend(attrs = {
@JsonAppend.Attr(value = "version")
})
public class BeanWithAppend {
private int id;
private String name;
// constructor, getters and setters
}

与上一个类似的测试将验证当应用*@JsonAppend*注解时，在序列化之后会包含补充属性:

BeanWithAppend bean = new BeanWithAppend(2, "Bean With Append Annotation");
ObjectWriter writer
= mapper.writerFor(BeanWithAppend.class).withAttribute("version", "1.0");
String jsonString = writer.writeValueAsString(bean);

该序列化的输出显示version属性已被添加:

{
"id": 2,
"name": "Bean With Append Annotation",
"version": "1.0"
}

4. @JsonNaming

@JsonNaming注解用于为序列化中的属性选择命名策略，覆盖默认策略。使用value元素，我们可以指定任何策略，包括自定义策略。

除了默认的LOWER_CAMEL_CASE(例如lowerCamelCase)， Jackson库为我们提供了其他四种内置的属性命名策略以方便我们:

• LOWER_CAMEL_CASE: 默认模式, 名称元素，除了第一个小写，后面的都以大写字母开头，后面跟着小写字母，并且没有分隔符，例如: lowerCamelCase。
• KEBAB_CASE: 名称元素用连字符分隔，例如: kebab-case。
• LOWER_CASE: 所有的字母都是小写的，没有分隔符，例如: kebabcase。
• SNAKE_CASE: 所有的字母都是小写的，下划线作为名称元素之间的分隔符，例如: snake_case。
• UPPER_CAMEL_CASE: 所有名称元素，包括第一个，都以大写字母开头，后面跟着小写字母，并且没有分隔符，例如: UpperCamelCase。
• LOWER_DOT_CASE: 名称元素用点分隔，例如: kebab.case。

本例将演示如何使用 蛇形大小写名称(snake case) 序列化属性，其中名为beanName的属性被序列化为: bean_name.

给定一个bean定义:

@JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class)
public class NamingBean {
private int id;
private String beanName;
// constructor, getters and setters
}

下面的测试演示了指定的命名规则按要求工作:

NamingBean bean = new NamingBean(3, "Naming Bean");
String jsonString = mapper.writeValueAsString(bean);
assertThat(jsonString, containsString("bean_name"));

The jsonString variable contains following data:

{
"id": 3,
"bean_name": "Naming Bean"
}

5. @JsonPropertyDescription

Jackson库能够在一个名为JSON Schema的独立模块的帮助下为Java类型创建JSON模式。当我们想要在序列化Java对象时指定预期输出，或者在反序列化之前验证JSON文档时，该模式非常有用。

@JsonPropertyDescription 注解允许通过提供 description 字段将人类可读的描述添加到创建的 JSON 模式中。

本节使用下面声明的bean来演示*@JsonPropertyDescription*的功能:

public class PropertyDescriptionBean {
private int id;
@JsonPropertyDescription("This is a description of the name property")
private String name;
// getters and setters
}

通过添加description字段生成JSON模式的方法如下所示:

SchemaFactoryWrapper wrapper = new SchemaFactoryWrapper();
mapper.acceptJsonFormatVisitor(PropertyDescriptionBean.class, wrapper);
JsonSchema jsonSchema = wrapper.finalSchema();
String jsonString = mapper.writeValueAsString(jsonSchema);
assertThat(jsonString, containsString("This is a description of the name property"));

我们可以看到，JSON模式的生成是成功的:

{
"type": "object",
"id": "urn:jsonschema:com:baeldung:jackson:annotation:extra:PropertyDescriptionBean",
"properties":
{
"name":
{
"type": "string",
"description": "This is a description of the name property"
},
"id":
{
"type": "integer"
}
}
}

6. @JsonPOJOBuilder

@JsonPOJOBuilder注解用于配置构建器类，以自定义JSON文档的反序列化，以便在命名约定与默认约定不同的情况下恢复POJO。

假设我们需要反序列化以下JSON字符串:

{
"id": 5,
"name": "POJO Builder Bean"
}

该JSON源将被用来创建一个POJOBuilderBean的实例:

@JsonDeserialize(builder = BeanBuilder.class)
public class POJOBuilderBean {
private int identity;
private String beanName;
// constructor, getters and setters
}

bean的属性名称与JSON字符串中的字段名称不同。这就是*@JsonPOJOBuilder*发挥作用的地方。

@JsonPOJOBuilder 注解带有两个属性:

• buildMethodName: 无参数方法的名称，用于在将JSON字段绑定到bean的属性之后实例化预期的bean。默认名称为“build”。
• withPrefix: 用于自动检测JSON和bean属性之间的匹配的名称前缀。默认前缀是 with。

这个例子使用了下面的BeanBuilder类，它在POJOBuilderBean上使用:

@JsonPOJOBuilder(buildMethodName = "createBean", withPrefix = "construct")
public class BeanBuilder {
private int idValue;
private String nameValue;
public BeanBuilder constructId(int id) {
idValue = id;
return this;
}
public BeanBuilder constructName(String name) {
nameValue = name;
return this;
}
public POJOBuilderBean createBean() {
return new POJOBuilderBean(idValue, nameValue);
}
}

在上面的代码中，我们配置了*@JsonPOJOBuilder*，以使用名为createBean的构建方法和construct前缀来匹配属性。

@JsonPOJOBuilder对bean的应用程序描述和测试如下:

String jsonString = "{"id":5,"name":"POJO Builder Bean"}";
POJOBuilderBean bean = mapper.readValue(jsonString, POJOBuilderBean.class);
assertEquals(5, bean.getIdentity());
assertEquals("POJO Builder Bean", bean.getBeanName());

结果显示，尽管属性名称不匹配，但已经成功地从JSON源重新创建了一个新的数据对象。

7. @JsonTypeId

@JsonTypeId注解用于指示在包含多态类型信息时，应该将注解属性序列化为类型id，而不是作为常规属性。该多态元数据在反序列化期间用于重新创建与序列化之前相同子类型的对象，而不是已声明的超类型的对象。

假设我们有一个bean类定义如下:

public class TypeIdBean {
private int id;
@JsonTypeId
private String name;
// constructor, getters and setters
}

下面的测试验证了*@JsonTypeId*的工作方式:

mapper.enableDefaultTyping(DefaultTyping.NON_FINAL);
TypeIdBean bean = new TypeIdBean(6, "Type Id Bean");
String jsonString = mapper.writeValueAsString(bean);
assertThat(jsonString, containsString("Type Id Bean"));

序列化过程的输出:

[
"Type Id Bean",
{
"id": 6
}
]

8. @JsonTypeIdResolver

@JsonTypeIdResolver 注解用于表示序列化和反序列化中的自定义类型标识处理程序。 该处理程序负责 Java 类型和 JSON 文档中包含的类型 id 之间的转换。

假设在处理以下类层次结构时，我们希望将类型信息嵌入到JSON字符串中。

AbstractBean 是超类:

@JsonTypeInfo(
use = JsonTypeInfo.Id.NAME,
include = JsonTypeInfo.As.PROPERTY,
property = "@type"
)
@JsonTypeIdResolver(BeanIdResolver.class)
public class AbstractBean {
private int id;
protected AbstractBean(int id) {
this.id = id;
}
// no-arg constructor, getter and setter
}

FirstBean 子类:

public class FirstBean extends AbstractBean {
String firstName;
public FirstBean(int id, String name) {
super(id);
setFirstName(name);
}
// no-arg constructor, getter and setter
}

LastBean 子类:

public class LastBean extends AbstractBean {
String lastName;
public LastBean(int id, String name) {
super(id);
setLastName(name);
}
// no-arg constructor, getter and setter
}

这些类的实例用于填充BeanContainer对象:

public class BeanContainer {
private List<AbstractBean> beans;
// getter and setter
}

我们可以看到AbstractBean类是用*@JsonTypeIdResolver注解的，这表明它使用自定义的TypeIdResolver*来决定如何在序列化中包含子类型信息，以及如何反过来使用元数据。

下面是处理包含类型信息的解析器类:

public class BeanIdResolver extends TypeIdResolverBase {
private JavaType superType;
@Override
public void init(JavaType baseType) {
superType = baseType;
}
@Override
public Id getMechanism() {
return Id.NAME;
}
@Override
public String idFromValue(Object obj) {
return idFromValueAndType(obj, obj.getClass());
}
@Override
public String idFromValueAndType(Object obj, Class<?> subType) {
String typeId = null;
switch (subType.getSimpleName()) {
case "FirstBean":
typeId = "bean1";
break;
case "LastBean":
typeId = "bean2";
}
return typeId;
}
@Override
public JavaType typeFromId(DatabindContext context, String id) {
Class<?> subType = null;
switch (id) {
case "bean1":
subType = FirstBean.class;
break;
case "bean2":
subType = LastBean.class;
}
return context.constructSpecializedType(superType, subType);
}
}

最值得注意的两个方法是idFromValueAndType和typeFromId，前者告诉在序列化pojo时包含类型信息的方式，后者使用该元数据确定重新创建的对象的子类型。

为了确保序列化和反序列化都能正常工作，让我们编写一个测试来验证完整的进度。

首先，我们需要实例化一个bean容器和bean类，然后用bean实例填充该容器:

FirstBean bean1 = new FirstBean(1, "Bean 1");
LastBean bean2 = new LastBean(2, "Bean 2");
List<AbstractBean> beans = new ArrayList<>();
beans.add(bean1);
beans.add(bean2);
BeanContainer serializedContainer = new BeanContainer();
serializedContainer.setBeans(beans);

接下来，将BeanContainer对象序列化，我们确认结果字符串包含类型信息:

String jsonString = mapper.writeValueAsString(serializedContainer);
assertThat(jsonString, containsString("bean1"));
assertThat(jsonString, containsString("bean2"));

序列化的输出如下所示:

{
"beans":
[
{
"@type": "bean1",
"id": 1,
"firstName": "Bean 1"
},
{
"@type": "bean2",
"id": 2,
"lastName": "Bean 2"
}
]
}

该JSON结构将用于重新创建与序列化之前相同子类型的对象。以下是反序列化的实现步骤:

BeanContainer deserializedContainer = mapper.readValue(jsonString, BeanContainer.class);
List<AbstractBean> beanList = deserializedContainer.getBeans();
assertThat(beanList.get(0), instanceOf(FirstBean.class));
assertThat(beanList.get(1), instanceOf(LastBean.class));

9. 结尾

本教程详细解释了几种不太常见的Jackson注解

最后

以上就是积极水壶为你收集整理的Jackson高级注解详解的全部内容，希望文章能够帮你解决Jackson高级注解详解所遇到的程序开发问题。

如果觉得靠谱客网站的内容还不错，欢迎将靠谱客网站推荐给程序员好友。