解决Jackson YAML序列化中多态类型标签的显示问题

本文旨在解决使用jackson进行多态类yaml序列化时，输出中出现不必要的原生类型标签（如`!`）的问题。我们将深入探讨该现象产生的原因，并提供一种通过配置`yamlmapper`禁用特定`yamlgenerator.feature`来有效移除这些标签的方法，从而实现与json序列化一致的简洁输出。

在Java开发中，Jackson库是处理JSON和YAML序列化与反序列化的强大工具。当涉及到多态类型的序列化时，我们通常会利用@JsonTypeInfo和@JsonSubTypes注解来指定类型信息如何嵌入到输出中。例如，我们可以选择将类型信息作为现有属性（JsonTypeInfo.As.EXISTING_PROPERTY）来表示，这在JSON输出中表现良好，能够生成简洁且易于理解的结构。然而，在使用jackson-dataformat-yaml进行YAML序列化时，即使已指定类型信息作为现有属性，输出中仍可能出现额外的原生YAML类型标签，如!或!，这与我们期望的简洁输出不符。

理解问题现象

考虑以下一组Java类，它们定义了一个多态的Vehicle接口及其实现类Car和Truck，以及一个包含Vehicle列表的Vehicles容器类。我们使用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.dataformat.yaml.YAMLGenerator;
import com.fasterxml.jackson.dataformat.yaml.YAMLMapper;
import com.google.common.collect.ImmutableList;
import lombok.Value;

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

public class PolymorphicSerializationExample {

    @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();
    }

    @Value
    public static class Car implements Vehicle {
        String name;
        String type = "car"; // 类型信息作为现有属性

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

    @Value
    public static class Truck implements Vehicle {
        String name;
        String type = "truck"; // 类型信息作为现有属性

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

    @Value
    public static class Vehicles {
        List<Vehicle> vehicles;

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

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

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

        // 序列化为JSON
        final String 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 (Problematic) ---");
        System.out.println(yaml);
    }
}

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

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

--- YAML Output (Problematic) ---
vehicles:
- !<car>
  name: "Dodge"
  type: "car"
- !<truck>
  name: "Scania"
  type: "truck"

可以看到，JSON输出非常干净，没有额外的类型信息。然而，YAML输出中却出现了!和!这样的原生YAML标签，这增加了输出的冗余性，并且可能不是我们期望的格式。

解决方案：禁用原生类型ID特性

造成YAML输出中出现这些原生类型标签的原因是jackson-dataformat-yaml库中的一个默认特性：YAMLGenerator.Feature.USE_NATIVE_TYPE_ID。当此特性启用时，Jackson会尝试使用YAML的原生标签机制来表示多态对象的类型信息。尽管我们已经通过@JsonTypeInfo(include = JsonTypeInfo.As.EXISTING_PROPERTY)将类型信息嵌入到了对象的一个属性中，YAMLGenerator仍然会额外地生成这些原生标签。

皮卡智能

AI驱动高效视觉设计平台

下载

要解决这个问题，只需在构建YAMLMapper时显式禁用YAMLGenerator.Feature.USE_NATIVE_TYPE_ID特性即可。

import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator;
import com.fasterxml.jackson.dataformat.yaml.YAMLMapper;
import com.fasterxml.jackson.databind.ObjectMapper;
// ... 其他导入

public class PolymorphicSerializationExample {
    // ... Vehicle, Car, Truck, Vehicles 类定义

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

        // 修正后的YAML Mapper配置
        ObjectMapper YAML_MAPPER = YAMLMapper.builder()
            .disable(YAMLGenerator.Feature.WRITE_DOC_START_MARKER)
            .disable(YAMLGenerator.Feature.USE_NATIVE_TYPE_ID) // 禁用原生类型ID特性
            .build();

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

        final String 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 (Corrected) ---");
        System.out.println(yaml);
    }
}

验证修正后的输出

重新运行修改后的代码，我们将得到期望的YAML输出：

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

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

可以看到，!和!这样的原生YAML类型标签已经被成功移除，YAML输出变得与JSON输出一样简洁，且类型信息仍通过type属性正确地保留。

总结

当使用Jackson进行多态对象的YAML序列化，并且希望避免输出中出现原生YAML类型标签（如!）时，关键在于禁用YAMLGenerator.Feature.USE_NATIVE_TYPE_ID特性。这个特性默认是启用的，它指示Jackson使用YAML的原生机制来表示类型。通过将其禁用，我们确保了即使在多态场景下，YAML输出也能保持简洁，尤其是在类型信息已通过@JsonTypeInfo.As.EXISTING_PROPERTY等方式嵌入到对象属性中的情况下，这提供了与JSON序列化一致的输出风格。理解并正确配置YAMLGenerator的特性，有助于我们更好地控制YAML输出的格式和内容，满足特定的应用需求。