ASP.NET Web API含Locale实体的无限序列化问题求解

我正在开发ASP.NET Web API，遇到了实体序列化相关的问题：Car类关联了包含Locale的Color、Transmission等类，当从数据库获取数据并通过控制器返回时，进程因序列化无法完成而挂起。

我已经尝试过设置Newtonsoft的ReferenceLoopHandling为Ignore，以及JsonSerializerOptions.ReferenceHandler为Preserve，但都没有效果。想请教有没有其他配置方案或者类结构优化方式可以解决这个问题？

相关类结构 #

Car类 #

public class Car : IEntity
{
    public int Id { get; set; }
    public int? OwnerId { get; set; }
    public int BrandId { get; set; }
    public int ModelId { get; set; }
    public int ReleaseYearId { get; set; }
    public int ColorId { get; set; }
    public int MarketId { get; set; }
    public int? RegionId { get; set; }
    public int GearTypeId { get; set; }
    public int CategoryId { get; set; }
    public int FueltypeId { get; set; }
    public int CurrencyId { get; set; }
    public int? AutoSalonId { get; set; }
    public int TransmissionId { get; set; }
    public ushort EngineVolume { get; set; }
    public ushort HorsePower { get; set; }
    public DateTime LastUpdated { get; set; }
    public string? Description { get; set; }
    public int Mileage { get; set; }
    public int MileageTypeId { get; set; }
    public int Price { get; set; }
    public ushort? SeatCount { get; set; }
    public bool CreditAvailable { get; set; }
    public bool BarterAvailable { get; set; }
    public List<Image> Images { get; set; } = new();
    public List<Feature> Features { get; set; } = new();

    public User? Owner { get; set; }
    public Brand? Brand { get; set; }
    public Model? Model { get; set; }
    public Year? Year { get; set; }
    public Color? Color { get; set; }
    public Region? Region { get; set; }
    public Market? Market { get; set; }
    public GearType? GearType { get; set; }
    public Category? Category { get; set; }
    public FuelType? Fueltype { get; set; }
    public Currency? Currency { get; set; }
    public MileageType? MileageType { get; set; }
    public Transmission? Transmission { get; set; }
    public AutoSalon? AutoSalon { get; set; }

    public Car() { }
}

Color与Transmission相关类 #

public class Color : IEntity
{
    public int Id { get; set; }

    public List<ColorLocale>? ColorLocales { get; set; } 

    public Color() { }
}

public class ColorLocale : IEntity
{
    public int Id { get; set; }
    public int LanguageId { get; set; }
    public string Name { get; set; } = string.Empty;

    public Color? Color { get; set; }
    public Language? Language { get; set; }

    public ColorLocale() { }
} 

public class Transmission : IEntity
{
    public int Id { get; set; }

    public List<TransmissionLocale>? TransmissionLocales { get; set; }

    public Transmission() { }
}

public class TransmissionLocale : IEntity
{
    public int Id { get; set; }
    public int LanguageId { get; set; }
    public string Name { get; set; } = string.Empty;

    public Language? Language { get; set; }
    public Transmission? Transmission { get; set; }

    public TransmissionLocale() { }
}

控制器代码 #

[HttpPost("getcars")]
public async Task<ActionResult<List<Car>>> GetCars(int pageNumber = 1, int pageSize = 20)
{
    var carList = await _carService.GetCarsWithPagination("", pageNumber, pageSize);
    return carList;
}

解决方案 #

1. 控制EF Core数据加载范围（从根源避免循环） #

序列化挂起的核心原因是EF Core加载了深层关联数据，形成循环引用链（比如Color→ColorLocale→Color→Language→...）。你需要在查询时只加载前端需要的内容：

• 在GetCarsWithPagination方法中，使用Include明确指定要加载的关联，或直接通过投影筛选字段：

// 服务层查询示例：只取需要的字段，避免加载完整关联实体
var cars = await _context.Cars
    .Skip((pageNumber - 1) * pageSize)
    .Take(pageSize)
    .Select(c => new 
    {
        c.Id,
        c.EngineVolume,
        c.HorsePower,
        c.Price,
        // 只取当前语言对应的颜色名称
        ColorName = c.Color.ColorLocales.FirstOrDefault(cl => cl.LanguageId == 当前请求语言ID)?.Name,
        // 变速箱名称同理
        TransmissionName = c.Transmission.TransmissionLocales.FirstOrDefault(tl => tl.LanguageId == 当前请求语言ID)?.Name
    })
    .ToListAsync();

2. 使用DTO（数据传输对象） #

不要直接返回EF实体给前端，定义专门的DTO类，只包含前端需要的字段，彻底切断不必要的关联：

// 示例CarDTO
public class CarDTO
{
    public int Id { get; set; }
    public ushort EngineVolume { get; set; }
    public ushort HorsePower { get; set; }
    public int Price { get; set; }
    public string? ColorName { get; set; }
    public string? TransmissionName { get; set; }
    // 其他前端需要的字段...
}

然后在服务层将实体映射为DTO（可以用AutoMapper简化映射逻辑）：

public async Task<List<CarDTO>> GetCarsWithPagination(string filter, int pageNumber, int pageSize)
{
    var currentLangId = /* 获取当前请求的语言ID */;
    return await _context.Cars
        .Skip((pageNumber - 1) * pageSize)
        .Take(pageSize)
        .Select(c => new CarDTO
        {
            Id = c.Id,
            EngineVolume = c.EngineVolume,
            HorsePower = c.HorsePower,
            Price = c.Price,
            ColorName = c.Color.ColorLocales.FirstOrDefault(cl => cl.LanguageId == currentLangId)?.Name,
            TransmissionName = c.Transmission.TransmissionLocales.FirstOrDefault(tl => tl.LanguageId == currentLangId)?.Name
        })
        .ToListAsync();
}

3. 修正序列化配置 #

如果坚持返回实体，确保序列化配置正确生效：

Newtonsoft.Json配置（ASP.NET Core 3.0前默认或手动启用）

services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore;
        options.SerializerSettings.NullValueHandling = NullValueHandling.Ignore; // 忽略null值，减少数据量
    });

System.Text.Json配置（ASP.NET Core 3.0+默认）

services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles; // 直接忽略循环引用
        options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
    });

注意：ReferenceHandler.Preserve会保留循环引用并生成$id元数据，不是解决挂起的最优方案，改用IgnoreCycles更直接。

4. 禁用EF Core延迟加载 #

如果上下文开启了延迟加载，序列化时会自动加载所有导航属性，导致大量冗余数据和循环。可以在上下文构造中禁用：

public class YourDbContext : DbContext
{
    public YourDbContext(DbContextOptions<YourDbContext> options) : base(options)
    {
        this.ChangeTracker.LazyLoadingEnabled = false;
    }
}

内容的提问来源于stack exchange，提问作者Mətin Abaszadə