解决C# Web API中EF实体循环引用序列化错误

你遇到的问题确实是User与ToDoList双向导航属性引发的循环引用，ASP.NET Core默认的Json序列化器无法处理这种循环嵌套。下面是几种有效的解决方法：

方案1：使用数据传输对象（DTO）【推荐】 #

创建仅包含前端需要字段的DTO，切断实体间的循环引用，同时避免暴露敏感字段（比如Password）。

步骤： #

1. 定义DTO类：

public class ToDoListDto
{
    public Guid Id { get; set; }
    public string? Title { get; set; }
    public List<ToDoDto>? ToDos { get; set; }
}

public class ToDoDto
{
    public Guid Id { get; set; }
    public string? Name { get; set; }
    public string? Description { get; set; }
    public bool? InProgress { get; set; }
    public bool? IsComplete { get; set; }
    public DateTime Created { get; set; }
}

2. 修改控制器代码，将实体转换为DTO：

[HttpGet("{userId}/todolists")]
public async Task<ActionResult<IEnumerable<ToDoListDto>>> GetToDoListsForUser(Guid userId)
{
    var user = await _userService.GetToDoListsForUsers(userId);

    if (user == null)
    {
        return NotFound("User not found");
    }

    var toDoLists = user.ToDoLists;

    if (toDoLists == null || !toDoLists.Any())
    {
        return NotFound("user has no lists");
    }

    // 转换为DTO
    var dtoList = toDoLists.Select(list => new ToDoListDto
    {
        Id = list.Id,
        Title = list.Title,
        ToDos = list.ToDos?.Select(todo => new ToDoDto
        {
            Id = todo.Id,
            Name = todo.Name,
            Description = todo.Description,
            InProgress = todo.InProgress,
            IsComplete = todo.IsComplete,
            Created = todo.Created
        }).ToList()
    }).ToList();

    return Ok(dtoList);
}

方案2：配置全局Json序列化选项 #

在Program.cs中全局配置Json序列化器，处理循环引用：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 方式1：忽略循环引用（直接跳过引发循环的属性）
        options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
        
        // 方式2：保留引用，用$id标记循环对象（适合需要保留引用关系的场景）
        // options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.Preserve;
    });

这种方法无需修改实体或控制器代码，全局生效。IgnoreCycles更简洁，适合大多数常规场景。

方案3：在实体类上标记[JsonIgnore] #

直接在反向导航属性上添加[JsonIgnore]特性，序列化时忽略该属性：

public class ToDoList
{
    public Guid Id { get; set; }
    public string? Title { get; set; }
    public List<ToDo>? ToDos { get; set; }

    public Guid UserId { get; set; }
    // 添加JsonIgnore，序列化ToDoList时不会包含User
    [JsonIgnore]
    public User? User { get; set; }
}

按需选择忽略的方向，如果需要序列化User时不包含ToDoLists，也可以在User类的ToDoLists属性上添加[JsonIgnore]。

方案4：EF查询时使用投影 #

修改EF查询语句，直接投影出需要的字段，不加载完整实体：

// 修改服务层方法
public Task<List<ToDoListDto>> GetToDoListsForUsers(Guid userId)
{
    return _context.Users
        .Where(u => u.Id == userId)
        .SelectMany(u => u.ToDoLists)
        .Select(list => new ToDoListDto
        {
            Id = list.Id,
            Title = list.Title,
            ToDos = list.ToDos?.Select(todo => new ToDoDto
            {
                Id = todo.Id,
                Name = todo.Name,
                Description = todo.Description,
                InProgress = todo.InProgress,
                IsComplete = todo.IsComplete,
                Created = todo.Created
            }).ToList()
        })
        .ToListAsync();
}

这种方法不需要加载完整的User实体，直接获取需要的待办列表数据，效率更高，同时避免循环引用。

为什么你之前的方法无效？ #

你手动序列化反序列化的步骤只是处理了User对象，但最终返回的toDoLists仍然是包含User引用的原始实体集合。ASP.NET Core返回Ok(toDoLists)时，会使用全局的Json序列化配置（而非你手动创建的jsonSettings）进行序列化，因此循环引用问题依然存在。

内容的提问来源于stack exchange，提问作者Yusuf