C#自带JSON序列化如何处理循环引用？

Question

在使用C#自带的 `System.Text.Json` 进行JSON序列化时，如何处理对象图中的循环引用（如父子对象相互引用）是一个常见问题。默认情况下，序列化器会抛出异常，防止无限递归。那么，如何配置 `JsonSerializerOptions` 来妥善处理循环引用？是否可以通过设置 `ReferenceHandler` 选项来保留对象引用？不同项目类型（如.NET Core 3.1与.NET 5+）对此的支持是否存在差异？开发者该如何选择合适的策略以确保数据完整性与序列化性能？

Answer 1

一、背景与问题描述

在使用 C# 的 System.Text.Json 进行 JSON 序列化时，处理对象图中的循环引用（如父子对象相互引用）是一个常见的挑战。默认情况下，JsonSerializer 会抛出异常以防止无限递归。

例如，考虑如下类结构：

public class Parent
{
    public string Name { get; set; }
    public Child Child { get; set; }
}

public class Child
{
    public string Name { get; set; }
    public Parent Parent { get; set; }
}
  

如果一个 Parent 实例指向一个 Child 实例，而该 Child 又反过来引用同一个 Parent，序列化器将无法正确遍历整个对象图。

二、解决方案概述

为了解决这一问题，.NET 提供了多种方式来配置 JsonSerializerOptions，从而控制如何处理对象之间的引用关系。

• 设置 ReferenceHandler 属性
• 自定义类型转换器（JsonConverter）
• 忽略某些属性或使用条件序列化

三、深度解析：ReferenceHandler 配置

ReferenceHandler 是 .NET 5 中引入的新特性，用于在序列化过程中跟踪和处理对象引用。

其主要取值包括：

选项	行为说明
Preserve	保留对象引用并生成带 $id 和 $ref 的 JSON 结构
IgnoreCycles	忽略循环引用路径，不抛出异常，但可能丢失数据
Default	默认行为，遇到循环引用抛出异常

示例代码：

var options = new JsonSerializerOptions
{
    ReferenceHandler = ReferenceHandler.Preserve,
    WriteIndented = true
};

var parent = new Parent { Name = "John" };
var child = new Child { Name = "Alice", Parent = parent };
parent.Child = child;

string json = JsonSerializer.Serialize(parent, options);
Console.WriteLine(json);
  

输出结果如下：

{
  "$id": "1",
  "Name": "John",
  "Child": {
    "$id": "2",
    "Name": "Alice",
    "Parent": {
      "$ref": "1"
    }
  }
}
  

四、版本差异分析：.NET Core 3.1 与 .NET 5+

ReferenceHandler 在 .NET Core 3.1 中不可用，开发者必须手动实现类似功能，例如通过以下方式：

• 使用 JsonConverter 自定义逻辑处理循环引用
• 在模型中添加标志位控制序列化行为
• 借助第三方库如 Newtonsoft.Json

从 .NET 5 开始，微软正式支持 ReferenceHandler，使得处理循环引用更加标准化和高效。

五、策略选择建议

开发者应根据项目需求和目标平台选择合适的策略：

1. 追求兼容性与简洁性：使用 IgnoreCycles 忽略循环路径，适用于不需要完整对象图的场景。
2. 需要保留完整对象结构：使用 Preserve 保留对象引用，确保反序列化后能还原原始结构。
3. 性能敏感型应用：避免频繁创建和追踪对象标识符，可采用自定义转换器或简化模型结构。

六、流程图展示

graph TD
      A[开始序列化] --> B{是否启用 ReferenceHandler?}
      B -- 否 --> C[抛出异常]
      B -- 是 --> D{ReferenceHandler 类型}
      D -- Preserve --> E[添加 $id 和 $ref]
      D -- IgnoreCycles --> F[跳过循环节点]
      D -- Default --> G[抛出异常]
      E --> H[完成序列化]
      F --> H
      G --> H

七、总结与展望

随着 .NET 平台的发展，System.Text.Json 在处理复杂对象图方面的能力不断增强。对于存在循环引用的对象模型，合理配置 ReferenceHandler 不仅可以避免异常，还能提升数据完整性和交互体验。