ASP.NET Core Web API中EF Core关联模型保存异常排查

在ASP.NET Core Web API项目中使用EF Core、DTO实现商品（Product）与分类（Category）的一对多关系（一个分类对应多个商品，一个商品归属一个分类）时，创建商品保存成功后，返回的商品数据中关联的Category属性值为null，异常返回结构如下：

[
  {
    "productId": 3,
    "title": "Swagger Test",
    "price": 20,
    "category": null,
    "desc": "Swagger Test",
    "absolute_Url": "Christian/Swagger Test",
    "postDate": "2022-07-15T13:18:42.0060792"
  }
]

• 实体定义不规范：Product实体中仅声明了Category引用导航属性，没有显式定义与导航属性匹配的外键字段CategoryId，EF Core会自动生成影子属性存储外键值，既容易出现映射时外键值未正确赋值的问题，也不利于后续的数据操作。
• 关联数据未显式加载：EF Core默认关闭懒加载，查询数据时不会自动加载导航属性关联的数据，只要查询逻辑中没有通过Include()方法指定加载Category导航属性，序列化返回的结果中Category就会为null。
• 接口逻辑缺失：当前创建商品的接口保存完成后直接返回无数据的Ok()结果，你看到的带null的返回值来自商品列表/详情查询接口，这类接口的查询逻辑完全没有做关联加载处理。
• 映射逻辑冗余：当前逻辑中手动查询分类实体再赋值给导航属性的写法，在没有显式外键的场景下，容易因为EF Core变更追踪的状态问题导致外键值未正确持久化。

1. 修正实体定义，显式声明外键字段 #

在Product实体中补充外键字段CategoryId，符合EF Core的默认关联约定，后续可以直接对外键赋值，减少全量查询关联实体的开销：

public class Product
{
    [Key]
    [Required]
    public int ProductId { get; set; }
    [Required]
    public string Title { get; set; }
    [Required]
    public double Price { get; set; }
    // 显式声明外键，与导航属性匹配
    [Required]
    public int CategoryId { get; set; }
    // 关联导航属性
    public Category Category { get; set; }
    [Required]
    public string Desc { get; set; }
    [Required]
    public string Absolute_Url { get; set; }
    [Required]
    public DateTime PostDate { get; set; }
}

Category实体可按需补充商品集合导航属性（非必须）：

public class Category
{
    [Key]
    [Required]
    public int CategoryId { get; set; }
    [Required]
    public string? Name { get; set; }
    // 可选：声明集合导航属性
    public List<Product> Products { get; set; }
}

2. 调整AutoMapper映射规则 #

直接配置DTO与实体的映射关系即可，显式声明外键后，AutoMapper会自动将DTO中的CategoryId映射到Product实体的同名字段，不需要额外配置：

// 映射配置
CreateMap<ProductDTO, Product>();
// 建议定义专门的响应DTO返回给前端，不要直接序列化数据库实体，避免循环引用、敏感字段泄露问题
CreateMap<Product, ProductResponseDTO>()
    .ForMember(dest => dest.CategoryName, opt => opt.MapFrom(src => src.Category.Name));

3. 修正创建接口逻辑 #

保留分类合法性校验，简化赋值流程，保存后如果需要返回完整商品信息，必须显式加载关联分类：

[HttpPost("Create")]
public async Task<ActionResult> Create([FromBody] ProductDTO productDTO)
{
    if (productDTO == null) return BadRequest("提交参数不能为空");
    if (!ModelState.IsValid) return BadRequest(ModelState);

    try
    {
        // 校验分类是否存在
        var category = await _uow.Category.FindById(productDTO.CategoryId);
        if(category == null) return BadRequest("所选商品分类不存在");

        var product = _mapper.Map<Product>(productDTO);
        product.PostDate = DateTime.Now;
        product.Absolute_Url = $"{category.Name}/{product.Title}";

        _uow.Product.Create(product);
        await _uow.Save();

        // 查询保存后的完整实体，必须Include加载关联分类
        var result = await _uow.Product
            .GetQueryable()
            .Include(p => p.Category)
            .FirstAsync(p => p.ProductId == product.ProductId);
        
        return Ok(result);
    }
    catch (Exception ex)
    {
        return BadRequest($"创建失败：{ex.Message}");
    }
}

4. 修正所有商品查询接口的关联加载逻辑 #

所有需要返回分类信息的查询接口，必须在查询时通过Include()指定加载Category导航属性，否则关联数据永远不会被查询出来：

// 商品列表查询示例
[HttpGet("List")]
public async Task<ActionResult> GetProductList()
{
    var list = await _uow.Product
        .GetQueryable()
        .Include(p => p.Category) // 核心：加载关联分类数据
        .ToListAsync();
    return Ok(list);
}

补充注意：如果在Category中定义了Products集合导航属性，序列化时会出现循环引用问题，需要在Program.cs中配置JSON序列化选项忽略循环引用：

builder.Services.AddControllers()
    .AddJsonOptions(opt =>
    {
        opt.JsonSerializerOptions.ReferenceHandler = System.Text.Json.Serialization.ReferenceHandler.IgnoreCycles;
    });

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