JacksonYAML多态序列化禁用类型标签

偷偷努力，悄无声息地变强，然后惊艳所有人！哈哈，小伙伴们又来学习啦~今天我将给大家介绍《Jackson YAML序列化：禁用类型标签实现多态一致输出》，这篇文章主要会讲到等等知识点，不知道大家对其都有多少了解，下面我们就一起来看一吧！当然，非常希望大家能多多评论，给出合理的建议，我们一起学习，一起进步！

本教程详细介绍了在使用Jackson进行多态对象YAML序列化时，如何解决默认生成原生类型标签（如`!`）的问题。通过禁用`YAMLGenerator.Feature.USE_NATIVE_TYPE_ID`特性，可以确保YAML输出与JSON输出保持一致，仅依赖自定义的类型属性进行多态信息表示，从而生成更简洁、易读的YAML结构。

在Java应用程序中，Jackson库是处理JSON和YAML数据序列化与反序列化的强大工具。尤其在处理多态类型（即一个接口或抽象类的不同实现）时，Jackson提供了@JsonTypeInfo和@JsonSubTypes等注解，允许开发者灵活地控制类型信息的嵌入方式。然而，当使用jackson-dataformat-yaml进行YAML序列化时，即使我们已经通过一个自定义属性来指示类型，YAML输出仍可能包含额外的原生类型标签，这可能导致输出冗余或不符合预期。

Jackson多态序列化机制概述

Jackson通过@JsonTypeInfo注解来配置多态类型信息的处理方式。常见的配置包括：

• use = JsonTypeInfo.Id.NAME：使用一个逻辑名称来表示类型。
• include = JsonTypeInfo.As.EXISTING_PROPERTY：将类型信息作为现有属性的值包含进来，而不是新增一个属性或包裹对象。
• property = "type"：指定哪个属性用于承载类型信息。

结合@JsonSubTypes，我们可以将接口或抽象类的不同实现映射到具体的类型名称。

考虑以下Java代码示例，它定义了一个Vehicle接口及其Car和Truck实现，并使用type属性来表示具体类型：

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.fasterxml.jackson.databind.annotation.JsonPOJOBuilder;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator;
import com.fasterxml.jackson.dataformat.yaml.YAMLMapper;
import lombok.Value;
import com.google.common.collect.ImmutableList;

import java.util.List;
import static java.util.Objects.requireNonNull;

// Vehicle 接口及其多态配置
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME,
    include = JsonTypeInfo.As.EXISTING_PROPERTY,
    property = "type")
@JsonSubTypes({
    @JsonSubTypes.Type(value = Car.class, name = "car"),
    @JsonSubTypes.Type(value = Truck.class, name = "truck") })
public interface Vehicle {
    String getName();
}

// Car 实现类
@Value
public static class Car implements Vehicle {
    String name;
    String type = "car"; // 明确指定类型属性

    @JsonCreator
    public Car(@JsonProperty("name") final String name) {
        this.name = requireNonNull(name);
    }
}

// Truck 实现类
@Value
public static class Truck implements Vehicle {
    String name;
    String type = "truck"; // 明确指定类型属性

    @JsonCreator
    public Truck(@JsonProperty("name") final String name) {
        this.name = requireNonNull(name);
    }
}

// 包含 Vehicle 列表的容器类
@Value
public static class Vehicles {
    List vehicles;

    @JsonCreator
    public Vehicles(@JsonProperty("vehicles") final List vehicles) {
        super();
        this.vehicles = requireNonNull(vehicles);
    }
}

public class SerializationDemo {
    public static void main(String[] args) throws JsonProcessingException {
        ObjectMapper JSON_MAPPER = new ObjectMapper();
        ObjectMapper YAML_MAPPER = YAMLMapper.builder()
            .disable(YAMLGenerator.Feature.WRITE_DOC_START_MARKER) // 禁用YAML文档开始标记
            .build();

        final Vehicles vehicles = new Vehicles(ImmutableList.of(new Car("Dodge"), new Truck("Scania")));

        // 序列化为JSON
        final String json = JSON_MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(vehicles);
        System.out.println("--- JSON Output ---");
        System.out.println(json);

        // 序列化为YAML
        final String yaml = YAML_MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(vehicles);
        System.out.println("\n--- YAML Output ---");
        System.out.println(yaml);
    }
}

运行上述代码，我们将得到以下输出：

--- JSON Output ---
{
  "vehicles" : [ {
    "name" : "Dodge",
    "type" : "car"
  }, {
    "name" : "Scania",
    "type" : "truck"
  } ]
}

--- YAML Output ---
vehicles:
- !
  name: "Dodge"
  type: "car"
- !
  name: "Scania"
  type: "truck"

可以看到，JSON输出非常简洁，类型信息完全由"type": "car"或"type": "truck"属性表示。然而，YAML输出中却出现了!和!这样的原生类型标签。这些标签在YAML规范中用于显式指定节点的类型，但在这里，它们与我们自定义的type属性重复，使得YAML输出显得冗余。

解决YAML原生类型标签问题

这种现象是由于jackson-dataformat-yaml默认启用了YAMLGenerator.Feature.USE_NATIVE_TYPE_ID特性。当Jackson检测到需要包含类型信息时（例如通过@JsonTypeInfo配置），并且此特性被启用时，它会尝试将这些类型信息映射为YAML的原生类型标签。

要解决这个问题，即移除这些冗余的原生类型标签，我们只需在构建YAMLMapper时禁用YAMLGenerator.Feature.USE_NATIVE_TYPE_ID特性即可。

修改YAMLMapper的构建代码如下：

import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator;
import com.fasterxml.jackson.dataformat.yaml.YAMLMapper;

// ... 其他导入和类定义 ...

public class SerializationDemo {
    public static void main(String[] args) throws JsonProcessingException {
        ObjectMapper JSON_MAPPER = new ObjectMapper();

        // 修改后的 YAML_MAPPER 配置
        ObjectMapper YAML_MAPPER = YAMLMapper.builder()
            .disable(YAMLGenerator.Feature.WRITE_DOC_START_MARKER)
            .disable(YAMLGenerator.Feature.USE_NATIVE_TYPE_ID) // 禁用原生类型标签
            .build();

        final Vehicles vehicles = new Vehicles(ImmutableList.of(new Car("Dodge"), new Truck("Scania")));

        final String json = JSON_MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(vehicles);
        System.out.println("--- JSON Output ---");
        System.out.println(json);

        final String yaml = YAML_MAPPER.writerWithDefaultPrettyPrinter().writeValueAsString(vehicles);
        System.out.println("\n--- YAML Output (Fixed) ---");
        System.out.println(yaml);
    }
}

再次运行修改后的代码，YAML输出将变为：

--- YAML Output (Fixed) ---
vehicles:
- name: "Dodge"
  type: "car"
- name: "Scania"
  type: "truck"

可以看到，!和!这些原生类型标签已经被成功移除，YAML输出变得与JSON输出一样简洁，完全依赖type属性来表示多态信息。

注意事项与最佳实践

1. 何时禁用USE_NATIVE_TYPE_ID：

   • 当你的多态类型信息已经通过自定义属性（如本例中的type字段）明确表示，并且你希望YAML输出更简洁、与JSON输出保持一致时。
   • 当你的YAML消费者不期望或不支持这些原生类型标签时。

2. 何时可能需要保留USE_NATIVE_TYPE_ID：

   • 如果你的多态配置没有使用EXISTING_PROPERTY，而是让Jackson自动添加一个类型属性（如@class），并且你希望YAML使用其原生标签机制来表示这些类型。
   • 如果你的YAML消费者（例如其他系统或语言的YAML解析器）期望或依赖这些原生类型标签来正确解析数据。
   • 在某些特定场景下，原生类型标签可能比自定义属性更符合YAML的惯例，但这种情况相对较少。

3. 保持一致性：在跨不同数据格式（JSON/YAML）进行序列化时，建议保持类型信息处理策略的一致性。如果JSON输出不包含额外的类型元数据，那么通常也希望YAML输出能达到相同的简洁度。

通过禁用YAMLGenerator.Feature.USE_NATIVE_TYPE_ID，开发者可以更好地控制Jackson在YAML序列化多态对象时的行为，生成更符合需求且易于理解的数据结构。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《JacksonYAML多态序列化禁用类型标签》文章吧，也可关注golang学习网公众号了解相关技术文章。