1. 概述
本文涵盖了上一篇文章《Jackson 注释指南》中未涵盖的一些附加注释 - 我们将介绍其中的七个注释。
2. @JsonIdentityReference
@JsonIdentityReference 用于自定义对对象的引用，这些对象将被序列化为对象标识而不是完整的 POJO。它与 @JsonIdentityInfo 协作，强制在每次序列化中使用对象标识，这与 @JsonIdentityReference 不存在时的第一次不同。在处理对象之间的循环依赖关系时，这两个注释非常有用。请参阅Jackson – 双向关系文章的第 4 节了解更多信息。
为了演示 @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 的 版本 元数据插入到相应的 JSON 文档中可能比为其提供附加属性更方便。
假设我们有一个没有 @JsonAppend 的 bean，如下所示：
public class BeanWithoutAppend {
private int id;
private String name;
// constructor, getters and setters
}
测试将确认，在没有 @JsonAppend 注释的情况下，序列化输出不包含有关补充 版本 属性的信息，尽管我们尝试添加到 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);
该序列化的输出显示 版本 属性已添加：
{
"id": 2,
"name": "Bean With Append Annotation",
"version": "1.0"
}
4. @JsonNaming
@JsonNaming 注解用于选择序列化中属性的命名策略，覆盖默认值。使用 value 元素，我们可以指定任何策略，包括自定义策略。
除了默认的 LOWER_CAMEL_CASE （例如 lowerCamelCase ）之外，Jackson 库还为我们提供了其他四种内置属性命名策略以方便使用：
- KEBAB_CASE ：名称元素用连字符分隔，例如 kebab-case 。
- LOWER_CASE ：所有字母均为小写，不带分隔符，例如 lowercase 。
- SNAKE_CASE ：所有字母均为小写，并用下划线作为名称元素之间的分隔符，例如 Snake_case 。
- UPPER_CAMEL_CASE ：所有名称元素（包括第一个元素）均以大写字母开头，后跟小写字母，并且没有分隔符，例如 UpperCamelCase 。
此示例将说明使用蛇形命名法序列化属性的方法，其中名为 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"));
jsonString 变量包含以下数据：
{
"id": 3,
"bean_name": "Naming Bean"
}
5. @JsonPropertyDescription
Jackson 库能够借助名为JSON Schema 的单独模块为 Java 类型创建 JSON 模式。当我们想要在序列化 Java 对象时指定预期输出，或者在反序列化之前验证 JSON 文档时，该模式非常有用。
@JsonPropertyDescription 注释允许通过提供 描述 字段将人类可读的描述添加到创建的 JSON 模式中。
本节使用下面声明的 bean 来演示 @JsonPropertyDescription 的功能：
public class PropertyDescriptionBean {
private int id;
@JsonPropertyDescription("This is a description of the name property")
private String name;
// getters and setters
}
添加 描述 字段生成 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 schema 生成成功：
{
"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。默认名称是 构建 。
- withPrefix ：自动检测 JSON 和 bean 属性之间匹配的名称前缀。默认前缀 是 .
此示例使用下面的 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 的 构建方法以及用于匹配属性的 构造 前缀。
@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，而不是常规属性。该多态元数据在反序列化过程中用于重新创建与序列化之前相同子类型的对象，而不是声明的超类型。
有关 Jackson 处理继承的更多信息，请参阅Jackson 的继承的第 2 节。
假设我们有一个 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 注释。这些示例和代码片段的实现可以在GitHub 项目中找到。