.NET EF Core 循环引用解决方案：JSON 序列化报错处理

在 .NET 开发中，使用 Entity Framework Core (EF Core) 进行 Product（商品）、Category（分类）及中间表多对多关联开发时，常遇到 JSON 序列化循环错误，即：

“A possible object cycle was detected”

本文将聚焦该场景的报错根源，结合实操案例详细讲解 生产环境推荐的 DTO 分层映射法，帮助开发者快速解决问题，避免踩坑。

一、报错场景还原

1. 实体关联结构

报错通常发生在三张表的多对多关联设计中，核心原因是 实体导航属性双向引用，导致序列化循环。具体结构如下：

Product（商品实体）
包含中间表集合属性（如 CategoryProducts），用于关联所属分类。
Category（分类实体）
包含中间表集合属性（如 ProductCategories），用于关联下属商品。
CategoryProduct（中间表）
同时包含 Product 和 Category 的导航属性，形成双向关联。

2. 典型报错信息

[ERR] A possible object cycle was detected. This can either be due to a cycle 
or if the object depth is larger than the maximum allowed depth of 64. 
Consider using ReferenceHandler.Preserve on JsonSerializerOptions to support cycles. 
Path: $.Products.Product.CategoryProducts.Product.CategoryProducts...

报错提示对象循环被检测到，序列化无法继续。

二、核心解决方案：DTO 分层映射法（生产环境首选）

核心思路：通过自定义 DTO（数据传输对象）拆分循环关联，精准控制导航属性，彻底根治 JSON 序列化循环错误，同时兼顾接口性能和数据安全性。

映射中间表时，拆分出“完整 DTO”与“简化 DTO”。
ProductDto 关联 简化版中间表 DTO（删除 Product 导航属性），避免循环。
CategoryDto 沿用 完整中间表 DTO，满足业务查询需求。

1. 分层 DTO 设计

以下示例可根据实际业务字段灵活补充属性：

// 1. 商品 DTO（完整版）：关联简化版中间表 DTO，避免循环
public class ProductDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public ICollection<CategoryProductSimpleDto> CategoryProducts { get; set; }
}

// 2. 分类 DTO（完整版）：关联完整中间表 DTO
public class CategoryDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public ICollection<CategoryProductDto> ProductCategories { get; set; }
}

// 3. 中间表完整 DTO：用于中间表单独查询及 CategoryDto 关联
public class CategoryProductDto
{
    public int Id { get; set; }
    public int ProductId { get; set; }
    public int CategoryId { get; set; }
    public ProductDto Product { get; set; }
    public CategoryDto Category { get; set; }
}

// 4. 中间表简化 DTO（核心）：删除 Product 导航属性，打破循环
public class CategoryProductSimpleDto
{
    public int Id { get; set; }
    public int ProductId { get; set; }
    public int CategoryId { get; set; }
    public CategoryDto Category { get; set; } // 可选，根据需求保留
}

2. 核心优势

彻底根治循环：ProductDto 关联简化版中间表 DTO，CategoryDto 使用完整 DTO，但因 ProductDto 已简化，闭环被打破。
数据可控：按需返回字段，避免冗余，提高接口响应速度。
安全合规：DTO 隐藏实体内部结构，减少敏感字段泄露风险。
灵活拓展：可根据接口需求调整 DTO 字段，兼容性强。

三、避坑指南

1. 常见错误排查

映射混淆：确保 ProductDto 关联简化 DTO，CategoryDto 关联完整 DTO，不要两者都关联完整 DTO。
序列化深度不足：可配置 JsonSerializerOptions.MaxDepth，但优先通过 DTO 打破循环。
映射工具配置：如使用 AutoMapper，需注册简化 DTO 的映射规则，避免遗漏。

2. 方案选型说明

生产环境：推荐 DTO 分层映射法，彻底解决循环引用，易于维护。
调试/临时方案：可使用 .NET 官方 JSON 配置 ReferenceHandler.Preserve，但可能导致数据冗余，不建议长期使用。

四、总结

在 .NET EF Core 中，Product、Category 及中间表的 JSON 循环引用问题，根本原因是 导航属性形成闭环依赖。

采用 DTO 分层映射法：

ProductDto 关联 简化中间表 DTO
CategoryDto 关联 完整中间表 DTO

即可满足业务需求，同时彻底解决序列化报错。

此思路同样适用于其他循环引用场景（如一对多、一对一），核心原则是 打破导航属性闭环，按需控制返回数据层级。