在类结构变化时的兼容性

1. 引言

想象一下：你写了一个类 Person，把对象序列化到文件里，过几个月你决定给它加个住址字段，或者改了某些属性的类型。看起来很正常——但当你尝试加载（反序列化）以前保存的老格式数据时，可能会有惊喜：有东西加载不出来，会抛异常，某些值会变成空或者甚至不对。

这种行为就是典型的向后兼容性问题。在真实开发中这种情况比学生忘记写分号还常见（也就是非常常见）。

通过示例说明问题

看我们的小教学项目。假设现在我们有这样的类：

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
}

把这个类的实例序列化成 JSON：

Person p = new Person { Name = "艾丽斯", Age = 35 };
string json = JsonSerializer.Serialize(p);
File.WriteAllText("person.json", json);

文件里会是：

{"Name":"艾丽斯","Age":35}

一周后我们想让应用更时髦，给它加个地址字段：

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public string Address { get; set; } // 新字段
}

然后我们尝试加载老文件：

string json = File.ReadAllText("person.json");
Person p = JsonSerializer.Deserialize<Person>(json);

会发生什么？我们的对象没有地址：属性 Address 会是 null。没有报错。现在还好……但一旦你开始改类型、删字段或做更“有意思”的改动，麻烦就来了！

2. 常见变更类型及其影响

类结构的变化会以不同方式影响序列化。我们来看看几种典型场景。

添加新属性

这是最不危险的情况。老数据（没有这些属性）通常能正常反序列化：新属性会获得默认值（引用类型是 null，0 对 int 等）。

注意： 如果你的新属性不是 nullable 且没有“合理”的默认值，就可能出问题（尤其是 C# 11+ 的 required 属性）。

删除属性

如果你删除了某个属性，但序列化的数据里还存在它——序列化器通常会忽略这些“多余”的字段，加载仍能进行。

不过这取决于所用的序列化器。比如 JsonSerializer 和 Newtonsoft.Json 比较宽容：它们不会抛异常，但一些老或自定义序列化器可能不一样。

重命名属性

这里就麻烦了。如果你把属性从 FirstName 重命名为 Name，序列化器不会自动把老数据的字段映射到新属性。也就是说，属性会是空的（null/0），文件里的旧字段会被忽略。

改变属性类型

比如以前你是 public int Age，后来你改成 public string Age（也许有人会写 "immortal"）。反序列化老数据可能会报错（比如 "Cannot convert number to string"）或者属性拿到默认值。一切取决于序列化器和它的严格性设置。

改变继承或嵌套结构

如果你改了基类、把属性搬到别处，或者把类包成另一个类——老序列化数据可能完全不兼容。特别是对 XML 和复杂对象层次结构，这种情况更容易出问题。

3. 兼容性问题的表现

怎么发现兼容性问题？

兼容性问题常常不会立刻显现：应用可能只是“行为怪怪的”，部分数据丢失，或者日志里只有含糊的异常信息。通常问题会在以下场景浮现：

• 用户在新版程序里加载老文件。
• 服务器收到来自“老版本”客户端的 JSON/XML。
• 你依赖的外部 API 突然更新了接口。

症状多种多样：从反序列化错误到“意外”的空字段都有可能。

序列化器对兼容性的影响

不同序列化器行为不同。对 JSON 来说，像标准的 System.Text.Json 和 Newtonsoft.Json 通常对结构变化比较“容忍”。它们会跳过文件里不认识的属性，也不会把对象里不认识的字段序列化回去。

对 XML 来说就严格些：如果根元素或层次结构变化，可能会报错。

二进制格式如果顺序或类型变了，甚至可能抛出异常。

4. 降低风险的做法与实践

下面是一些能把麻烦降到最低的办法，常用且实用。

给类和数据使用版本号

在可序列化对象或文件里加个 Version 字段。这样可以判断文件是哪个结构版本生成的，加载时可以决定如何处理（比如执行升级逻辑）。

public class PersonV2
{
    public int Version { get; set; } = 2;
    public string Name { get; set; }
    public int Age { get; set; }
    public string Address { get; set; }
}

用名字映射属性（序列化时）

对 JSON 和 XML 可以明确指定序列化时属性的名字。如果你要重命名属性，保留旧名字映射：

public class Person
{
    [JsonPropertyName("FirstName")] // 给 System.Text.Json 用
    [JsonProperty("FirstName")]     // 给 Newtonsoft.Json 用
    public string Name { get; set; }
    public int Age { get; set; }
}

使用 nullable 类型和默认值

如果新增字段在老数据里可能不存在——把它设为 nullable 或者给个默认值，这样反序列化更安全：

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public string? Address { get; set; } = "Unknown";
}

处理“未知字段”事件

在 Newtonsoft.Json 里可以订阅未知字段的处理器，用来记录日志或做特殊处理，避免静默丢失信息。

var settings = new JsonSerializerSettings
{
    MissingMemberHandling = MissingMemberHandling.Error
};
try
{
    var person = JsonConvert.DeserializeObject<Person>(json, settings);
}
catch (JsonSerializationException ex)
{
    Console.WriteLine("无法反序列化: " + ex.Message);
}

数据迁移

如果改动很大，最好设计迁移步骤：先以“旧”结构加载数据，再把它转换为新结构。

// 假设旧的 PersonV1 没有 address
public class PersonV1 { public string Name; public int Age; }

// 新的有 address
public class PersonV2 { public string Name; public int Age; public string Address; }

// 迁移示例:
string oldJson = File.ReadAllText("person.json");
PersonV1 oldPerson = JsonSerializer.Deserialize<PersonV1>(oldJson);

PersonV2 migrated = new PersonV2
{
    Name = oldPerson.Name,
    Age = oldPerson.Age,
    Address = "Unknown"
};

5. 复杂场景与意外错误

字段不变性和 required 属性

从 C# 11 开始有了 required 属性。如果某字段被标记为 required，反序列化在数据缺失时可能会报错：

public class Person
{
    public string Name { get; set; }
    [JsonPropertyName("Age")]
    public required int Age { get; set; }
    public string Address { get; set; }
}

如果老数据里没有 Age 字段——会抛出结构不匹配的异常。

类型改变：int → string

// 之前:
public class Record { public int Count; }
// 之后:
public class Record { public string Count; }

如果数据里是 "Count":42，反序列化到 string 可能能成功（有时会自动转换），但反过来就可能抛异常。

删除基类

如果序列化对象曾继承某个基类，后来改了继承关系——老文件的反序列化可能出错，有时是静默失败，有时会抛异常。

6. 常见错误

错误 #1：随意修改现有属性。
在不考虑已有序列化数据的情况下重命名或改变属性类型，会导致反序列化时信息丢失。

错误 #2：给新字段忘记用 nullable。
新增属性要么是 nullable，要么给出合理默认值。

错误 #3：不测试向后兼容性。
改了类——一定要测试旧文件/数据能否被正确加载。

错误 #4：混用不同库的属性。
不要在同一属性上同时使用 JsonPropertyName 和 JsonProperty。