Entity Framework Code First 关系配置指南：Fluent API与Data Annotations

一、核心关系语义：Has与With

在 Entity Framework 中，配置实体关系主要围绕 "拥有者"（Principal）和 "依赖者"（Dependent）的关系展开。理解 Has（前者对后者的约束）与 With（后者对前者的约束）是正确配置的基础。

第1步：掌握基础约束类型

• HasOptional / HasRequired / HasMany：定义“前者”包含“后者”的情况。例如 A.HasRequired(a => a.B) 表示 A 类必须包含 B 类一个非空的实例。
• WithOptional / WithRequired / WithMany：定义“后者”包含“前者”的情况。例如 .WithOptional(b => b.A) 表示 B 可以包含 A 的一个实例或者为 null。

二、一对一关系（One-to-One）配置

一对一关系常见于主从场景，如用户与其详细资料照片。配置时需明确谁是主体（Principal），谁是依赖（Dependent）。在数据库中，通常表现为外键既作为关联字段，也作为自身的主键。

第1步：使用 Data Annotations 配置

Data Annotations 适合简单的外键标注。在依赖方实体中，将外键设为主键并关联到对方属性。

public class Person
{
    public int PersonId { get; set; }
    public string Name { get; set; }
    // 导航属性
    public PersonPhoto Photo { get; set; }
}

public class PersonPhoto
{
    // 外键也是主键
    [Key, ForeignKey("Person")] 
    public int PersonId { get; set; }
    public byte[] Image { get; set; }
    
    [ForeignKey("PersonId")]
    public Person Person { get; set; }
}

第2步：使用 Fluent API 配置关系模式

Fluent API 提供了更精确的控制能力，特别是处理不同的一对一种场景：

（1）1:0..1 关系（主从型）

主记录必须存在，从记录可选。这是最常见的“一人可有可无一张照片”场景。

modelBuilder.Entity<Person>()
    .HasOptional(p => p.Photo)       // Person 有可选的 Photo
    .WithRequired(p => p.Person);    // Photo 必须属于一个 Person

（2）1:1 关系（相互必选）

双方都必须存在，强制绑定。此时需显式指定 Principal（主）和 Dependent（从）。

modelBuilder.Entity<Person>()
    .HasRequired(p => p.Photo)
    .WithRequiredPrincipal(p => p.Person); // 指定 Person 为主体

三、一对多关系（One-to-Many）配置

如“目的地”对应多个“住宿点”。EF Code First 能自动推断简单的导航属性关系，但在需要自定义外键名、空值性或多重引用时需手动干预。

第1步：自动推断与规范命名

如果遵循标准命名（如 DestinationId 或 Target_DestinationId），EF 会自动创建外键且不为空。若希望外键可为空（即该住宿不一定要归属于某个景点），则外键定义为可空类型（int?）或使用 Fluent API 声明 Optional。

public class Lodging
{
    public int LodgingId { get; set; }
    // 可空外键允许不归属任何 Destination
    public int? DestinationId { get; set; } 
    public Destination Destination { get; set; }
}

第2步：自定义外键名

当属性命名不符合默认规范时，可通过以下方式指定：

1. Data Annotations

[ForeignKey("TarDestinationId")]
public Destination Target { get; set; }

2. Fluent API (MapKey)

modelBuilder.Entity<Destination>()
    .HasMany(d => d.Lodgings)
    .WithRequired(l => l.Destination)
    .Map(m => m.MapKey("CustomDestinationID"));

第3步：处理同一实体的多重引用

当 EntityA 中有两个导航属性指向 EntityB，或者反之，EF 无法自动分辨对应的关系链，会报错。需使用 InverseProperty（Annotations）或 WithMany 配合集合属性（Fluent API）来解耦。

public class Lodging
{
    public int PrimaryContactId { get; set; }
    // 指定 PrimaryContact 引用的是 Person.PrimaryContactFor 集合
    [InverseProperty("PrimaryContactFor")]
    public Person PrimaryContact { get; set; }

    [InverseProperty("SecondaryContactFor")]
    public Person SecondaryContact { get; set; }
}

第4步：配置级联删除（Cascade Delete）

EF 默认对非 Null 外键开启级联删除。若无需此行为或想改为 Null 级联，可进行配置：

// 关闭级联删除
modelBuilder.Entity<Destination>()
    .HasMany(d => d.Lodgings)
    .WithRequired(l => l.Destination)
    .WillCascadeOnDelete(false); 

全局关闭默认约定也可用：

modelBuilder.Conventions.Remove<CascadeDeleteConvention>();

四、多对多关系（Many-to-Many）配置

如“行程”与“活动”。EF Code First 默认自动生成中间连接表，无需手动创建实体类。

第1步：默认中间表配置

只要两个实体各自持有对方的 List<T> 集合，EF 即可识别。默认生成的表名为 Class1_Class2，联合主键为双方的 ID。

第2步：使用 Fluent API 指定表结构

若需自定义中间表名及外键字段名，使用 HasMany(...).WithMany(...).Map()：

modelBuilder.Entity<Trip>()
    .HasMany(t => t.Activities)
    .WithMany(a => a.Trips)
    .Map(m =>
    {
        m.ToTable("TripActivities");     // 自定义表名
        m.MapLeftKey("TripId");         // 左表外键
        m.MapRightKey("ActivityId");    // 右表外键
    });

五、常见问题排查

问题：配置了关系但生成的 SQL 没有外键约束？

原因与解决：如果使用的是 Nullable 类型外键且使用了 WillCascadeOnDelete(false)，部分数据库方言可能不会物理添加外键约束。建议使用 HasForeignKey 显式声明外键属性以确保一致性。

问题：上下文抛出有关循环引用的异常？

原因与解决：序列化或查询时可能出现循环。通常在 DTO 转换阶段处理，或在 JSON 序列化设置中添加 ReferenceLoopHandling.Ignore。