深入理解.NET文档中System.Text.Json多态序列化的正确用法

System.Text.Json是.NET平台中处理JSON数据的重要组件，其多态序列化功能允许开发者处理继承体系中的类型转换。本文将详细解析.NET文档中关于使用契约模型配置多态序列化的正确方法，并澄清一个常见的理解误区。

多态序列化的基本概念

多态序列化是指当JSON序列化/反序列化一个基类时，能够正确处理其派生类的特性。System.Text.Json提供了两种主要方式来实现这一功能：

1. 通过特性标注（Attribute-based）：在基类上使用JsonDerivedType特性
2. 通过契约模型（Contract model）：在运行时动态配置类型信息

契约模型的核心作用

契约模型特别适用于以下场景：

• 大型领域模型中难以修改所有基类
• 跨程序集的类型继承体系
• 第三方依赖中的类型层次结构
• 需要在运行时动态注册派生类型的情况

文档示例的深入解析

.NET文档中提供的C#示例使用了集合初始化器语法：

jsonTypeInfo.PolymorphismOptions = new JsonPolymorphismOptions
{
    TypeDiscriminatorPropertyName = "$point-type",
    IgnoreUnrecognizedTypeDiscriminators = true,
    UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FailSerialization,
    DerivedTypes =
    {
        new JsonDerivedType(typeof(ThreeDimensionalPoint), "3d"),
        new JsonDerivedType(typeof(FourDimensionalPoint), "4d")
    }
};

虽然这段代码看起来像是在设置DerivedTypes属性，但实际上它利用了C#的集合初始化器特性。编译器会将这种语法转换为对已存在集合的Add方法调用，而不是属性赋值。这是因为JsonPolymorphismOptions.DerivedTypes是一个只读的IList属性。

动态注册派生类型的正确方式

对于需要在运行时动态添加派生类型的场景，应该使用显式的Add方法调用：

jsonTypeInfo.PolymorphismOptions = new JsonPolymorphismOptions
{
    TypeDiscriminatorPropertyName = "$point-type",
    IgnoreUnrecognizedTypeDiscriminators = true,
    UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FailSerialization
};

jsonTypeInfo.PolymorphismOptions.DerivedTypes.Add(new JsonDerivedType(typeof(ThreeDimensionalPoint), "3d"));
jsonTypeInfo.PolymorphismOptions.DerivedTypes.Add(new JsonDerivedType(typeof(FourDimensionalPoint), "4d"));

这种方式特别适合以下情况：

• 开发库时需要允许第三方扩展注册新类型
• 派生类型列表在编译时未知
• 需要根据运行时条件动态添加类型

实际应用建议

在实际项目中，建议根据具体需求选择合适的方式：

1. 对于简单、固定的类型体系，可以使用特性标注或集合初始化器语法
2. 对于需要扩展性的场景，使用显式Add方法调用
3. 考虑封装类型注册逻辑，提供清晰的API给第三方扩展

通过正确理解和使用System.Text.Json的多态序列化功能，开发者可以构建更加灵活和可扩展的JSON处理逻辑，特别是在复杂的类型继承体系中。