.NET EF Core嵌套关联Include选项无法正常工作问题排查

问题核心原因 #

当你在EF Core中同时使用Include/ThenInclude和Select投影时，ThenInclude的作用会被Select覆盖——EF Core会优先处理投影逻辑，而非预加载的导航属性配置，这就容易引发InvalidOperationException。另外，也可能是实体间的导航属性配置不完整导致关联查询失败。

第一步：确认实体导航属性配置 #

先检查你的实体类是否正确配置了导航属性，以下是标准的配置示例：

public class UserCredentialMapping
{
    public int Id { get; set; }
    public int UserId { get; set; }
    // 导航属性：关联User
    public User User { get; set; }
}

public class User
{
    public int Id { get; set; }
    public string UserName { get; set; }
    // 导航属性：关联UserRoleMapping集合
    public ICollection<UserRoleMapping> UserRoleMappings { get; set; } = new List<UserRoleMapping>();
}

public class UserRoleMapping
{
    public int UserId { get; set; }
    public int RoleId { get; set; }
    // 导航属性：关联User和Role
    public User User { get; set; }
    public Role Role { get; set; }
}

public class Role
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
}

确保DbContext中正确配置了实体间的关系（比如使用Fluent API或数据注解），例如：

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    // 配置UserRoleMapping的复合主键
    modelBuilder.Entity<UserRoleMapping>()
        .HasKey(urm => new { urm.UserId, urm.RoleId });
    
    // 配置User与UserRoleMapping的一对多关系
    modelBuilder.Entity<User>()
        .HasMany(u => u.UserRoleMappings)
        .WithOne(urm => urm.User)
        .HasForeignKey(urm => urm.UserId);
    
    // 配置UserRoleMapping与Role的多对一关系
    modelBuilder.Entity<UserRoleMapping>()
        .HasOne(urm => urm.Role)
        .WithMany()
        .HasForeignKey(urm => urm.RoleId);
}

第二步：正确的查询写法 #

写法一：直接在Select投影中访问嵌套导航属性（推荐） #

这种方式不需要Include/ThenInclude，EF Core会自动将投影逻辑转换为对应的SQL关联查询，只获取你需要的字段，性能最优：

var credentialWithRoles = _context.UserCredentialMappings
    .Select(uc => new 
    {
        // UserCredentialMapping自身字段
        uc.Id,
        // 关联的User信息
        UserInfo = new 
        {
            uc.User.Id,
            uc.User.UserName
        },
        // 嵌套的Role详情
        UserRoles = uc.User.UserRoleMappings.Select(urm => new 
        {
            urm.Role.Id,
            urm.Role.Name,
            urm.Role.Description
        })
    })
    .ToList();

写法二：先预加载再投影（仅适合数据量小的场景） #

如果你坚持使用Include/ThenInclude预加载所有关联数据，需要先将数据加载到内存（调用ToList()），再进行投影。注意这种方式会加载所有关联实体的所有字段，数据量大时性能较差：

var credentialWithRoles = _context.UserCredentialMappings
    .Include(uc => uc.User)
        .ThenInclude(u => u.UserRoleMappings)
            .ThenInclude(urm => urm.Role)
    .ToList() // 先加载到内存
    .Select(uc => new 
    {
        uc.Id,
        UserName = uc.User.UserName,
        Roles = uc.User.UserRoleMappings.Select(urm => urm.Role)
    })
    .ToList();

额外注意：避免循环引用序列化问题 #

如果你的API直接返回包含关联实体的对象，可能会出现循环引用导致的序列化错误。可以在Program.cs中配置JSON序列化忽略循环引用：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
    });

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