本教程详细介绍了在使用jackson进行多态对象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<Vehicle> vehicles;
@JsonCreator
public Vehicles(@JsonProperty("vehicles") final List<Vehicle> 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:
- !<car>
name: "Dodge"
type: "car"
- !<truck>
name: "Scania"
type: "truck"可以看到，JSON输出非常简洁，类型信息完全由"type": "car"或"type": "truck"属性表示。然而，YAML输出中却出现了!<car>和!<truck>这样的原生类型标签。这些标签在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"
可以看到，!<car>和!<truck>这些原生类型标签已经被成功移除，YAML输出变得与JSON输出一样简洁，完全依赖type属性来表示多态信息。
注意事项与最佳实践
-
何时禁用USE_NATIVE_TYPE_ID：
- 当你的多态类型信息已经通过自定义属性（如本例中的type字段）明确表示，并且你希望YAML输出更简洁、与JSON输出保持一致时。
- 当你的YAML消费者不期望或不支持这些原生类型标签时。
-
何时可能需要保留USE_NATIVE_TYPE_ID：
- 如果你的多态配置没有使用EXISTING_PROPERTY，而是让Jackson自动添加一个类型属性（如@class），并且你希望YAML使用其原生标签机制来表示这些类型。
- 如果你的YAML消费者（例如其他系统或语言的YAML解析器）期望或依赖这些原生类型标签来正确解析数据。
- 在某些特定场景下，原生类型标签可能比自定义属性更符合YAML的惯例，但这种情况相对较少。
保持一致性：在跨不同数据格式（JSON/YAML）进行序列化时，建议保持类型信息处理策略的一致性。如果JSON输出不包含额外的类型元数据，那么通常也希望YAML输出能达到相同的简洁度。
通过禁用YAMLGenerator.Feature.USE_NATIVE_TYPE_ID，开发者可以更好地控制Jackson在YAML序列化多态对象时的行为，生成更符合需求且易于理解的数据结构。
