一对一关系配置 One-to-One

一对一关系基础

概念理解

一对一关系(One-to-One) 是指两个实体之间存在唯一的关联关系,一个实体实例只能关联另一个实体的一个实例。

csharp

public class User
{
    public int Id { get; set; }
    public string Username { get; set; }
    public string Email { get; set; }
    
    // 导航属性: 一个用户有一个配置文件
    public UserProfile Profile { get; set; }
}

public class UserProfile
{
    public int Id { get; set; }
    public string Bio { get; set; }
    public string Avatar { get; set; }
    public DateTime? BirthDate { get; set; }
    
    // 导航属性: 一个配置文件属于一个用户
    public User User { get; set; }
}

// 关系:
// User (1) ←→ (1) UserProfile
// 一个用户有且只有一个配置文件
// 一个配置文件只属于一个用户

数据库实现

sql

-- Users 表(主表)
CREATE TABLE Users (
    Id INT PRIMARY KEY IDENTITY(1,1),
    Username NVARCHAR(50) NOT NULL,
    Email NVARCHAR(100) NOT NULL
);

-- UserProfiles 表(从表)
CREATE TABLE UserProfiles (
    Id INT PRIMARY KEY IDENTITY(1,1),
    Bio NVARCHAR(500),
    Avatar NVARCHAR(200),
    BirthDate DATE,
    
    -- 外键(也是唯一约束,确保一对一)
    UserId INT NOT NULL UNIQUE,
    CONSTRAINT FK_UserProfiles_Users 
        FOREIGN KEY (UserId) REFERENCES Users(Id)
        ON DELETE CASCADE
);

-- 关键点:
-- 1. UserId 是外键,引用 Users.Id
-- 2. UserId 有 UNIQUE 约束,确保一对一
-- 3. 级联删除: 删除用户时自动删除配置文件

EF Core 约定

EF Core 的默认约定会自动检测一对一关系:

csharp

// 符合约定的写法: 无需额外配置
public class User
{
    public int Id { get; set; }
    public UserProfile Profile { get; set; }  // 导航属性
}

public class UserProfile
{
    public int Id { get; set; }
    public int UserId { get; set; }           // 外键属性
    public User User { get; set; }            // 导航属性
}

// EF Core 自动识别:
// - UserId 是外键(命名约定: <导航属性名><主键名>)
// - 一对一关系(因为两边都是单个对象,不是集合)

配置方式详解

方法 1: Fluent API(推荐)

csharp

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<User>()
        .HasOne(u => u.Profile)           // User 有一个 Profile
        .WithOne(p => p.User)             // Profile 有一个 User
        .HasForeignKey<UserProfile>(p => p.UserId);  // 指定外键
}

// 完整配置示例
modelBuilder.Entity<User>()
    .HasOne(u => u.Profile)
    .WithOne(p => p.User)
    .HasForeignKey<UserProfile>(p => p.UserId)
    .OnDelete(DeleteBehavior.Cascade);    // 级联删除

方法 2: 必需关系 vs 可选关系

必需关系(Required)

csharp

// UserProfile 必须有对应的 User
public class UserProfile
{
    public int Id { get; set; }
    public int UserId { get; set; }       // 非可空外键 → 必需
    public User User { get; set; }
}

// 配置
modelBuilder.Entity<User>()
    .HasOne(u => u.Profile)
    .WithOne(p => p.User)
    .HasForeignKey<UserProfile>(p => p.UserId)
    .IsRequired();  // 明确指定必需(默认就是)

// SQL:
// ALTER TABLE UserProfiles ADD CONSTRAINT FK_... 
// FOREIGN KEY (UserId) REFERENCES Users(Id) ON DELETE CASCADE;
// ↑ UserId NOT NULL

可选关系(Optional)

csharp

public class UserProfile
{
    public int Id { get; set; }
    public int? UserId { get; set; }      // 可空外键 → 可选
    public User User { get; set; }
}

// 配置
modelBuilder.Entity<User>()
    .HasOne(u => u.Profile)
    .WithOne(p => p.User)
    .HasForeignKey<UserProfile>(p => p.UserId)
    .IsRequired(false);  // 明确指定可选

// SQL:
// ALTER TABLE UserProfiles ADD CONSTRAINT FK_... 
// FOREIGN KEY (UserId) REFERENCES Users(Id);
// ↑ UserId NULL (允许没有用户的配置文件)

方法 3: 共享主键(Shared Primary Key)

csharp

// 不使用单独的外键列,直接用主键作为外键
public class User
{
    public int Id { get; set; }
    public UserProfile Profile { get; set; }
}

public class UserProfile
{
    public int Id { get; set; }  // 既是主键,也是外键
    public string Bio { get; set; }
    public User User { get; set; }
}

// 配置
modelBuilder.Entity<User>()
    .HasOne(u => u.Profile)
    .WithOne(p => p.User)
    .HasForeignKey<UserProfile>(p => p.Id);  // 使用主键作为外键

// SQL:
// CREATE TABLE UserProfiles (
//     Id INT PRIMARY KEY,  -- 与 Users.Id 相同
//     Bio NVARCHAR(500),
//     CONSTRAINT FK_UserProfiles_Users 
//         FOREIGN KEY (Id) REFERENCES Users(Id)
// );

// 优点:
// - 节省存储空间(不需要额外的 UserId 列)
// - 查询性能略好
// - 保证严格的一对一关系

// 缺点:
// - 插入顺序受限(必须先插入 User)
// - 不能独立创建 UserProfile

方法 4: 数据注解

csharp

public class User
{
    public int Id { get; set; }
    
    [InverseProperty(nameof(UserProfile.User))]
    public UserProfile Profile { get; set; }
}

public class UserProfile
{
    public int Id { get; set; }
    
    [ForeignKey(nameof(User))]
    public int UserId { get; set; }
    
    public User User { get; set; }
}

// ⚠️ 注意: 数据注解功能有限,复杂场景仍需 Fluent API

级联删除行为

DeleteBehavior 选项

1. Cascade(级联删除)

csharp

modelBuilder.Entity<User>()
    .HasOne(u => u.Profile)
    .WithOne(p => p.User)
    .HasForeignKey<UserProfile>(p => p.UserId)
    .OnDelete(DeleteBehavior.Cascade);  // 默认行为

// 效果: 删除用户时自动删除配置文件
var user = await context.Users.FindAsync(1);
context.Users.Remove(user);
await context.SaveChangesAsync();

// SQL:
// DELETE FROM UserProfiles WHERE UserId = 1;  -- 自动删除
// DELETE FROM Users WHERE Id = 1;

2. Restrict(限制删除)

csharp

modelBuilder.Entity<User>()
    .HasOne(u => u.Profile)
    .WithOne(p => p.User)
    .HasForeignKey<UserProfile>(p => p.UserId)
    .OnDelete(DeleteBehavior.Restrict);

// 效果: 如果存在配置文件,无法删除用户
var user = await context.Users.FindAsync(1);
context.Users.Remove(user);
await context.SaveChangesAsync();  // 💥 抛出异常!

// 必须先手动删除配置文件
var profile = await context.UserProfiles
    .FirstOrDefaultAsync(p => p.UserId == 1);
if (profile != null)
    context.UserProfiles.Remove(profile);

context.Users.Remove(user);
await context.SaveChangesAsync();  // ✅ 成功

3. SetNull(设为 NULL)

csharp

// 仅适用于可选关系
public class UserProfile
{
    public int Id { get; set; }
    public int? UserId { get; set; }  // 必须是可空
    public User User { get; set; }
}

modelBuilder.Entity<User>()
    .HasOne(u => u.Profile)
    .WithOne(p => p.User)
    .HasForeignKey<UserProfile>(p => p.UserId)
    .OnDelete(DeleteBehavior.SetNull);

// 效果: 删除用户时,配置文件的 UserId 设为 NULL
var user = await context.Users.FindAsync(1);
context.Users.Remove(user);
await context.SaveChangesAsync();

// SQL:
// UPDATE UserProfiles SET UserId = NULL WHERE UserId = 1;
// DELETE FROM Users WHERE Id = 1;

4. ClientSetNull(客户端设 NULL)

csharp

modelBuilder.Entity<User>()
    .HasOne(u => u.Profile)
    .WithOne(p => p.User)
    .HasForeignKey<UserProfile>(p => p.UserId)
    .OnDelete(DeleteBehavior.ClientSetNull);

// 效果: 类似 SetNull,但在客户端执行
// 需要手动加载相关实体

级联删除对比表

行为	删除主实体时	适用场景
Cascade	自动删除从实体	从实体依赖主实体存在
Restrict	阻止删除	需要保留从实体
SetNull	从实体外键设为 NULL	可选关系
ClientSetNull	客户端设置 NULL	需要精细控制

高级应用场景

场景 1: 加载一对一关系

csharp

// 方式 1: Include 预加载
var user = await context.Users
    .Include(u => u.Profile)
    .FirstOrDefaultAsync(u => u.Id == 1);

Console.WriteLine(user.Profile.Bio);  // OK,已加载

// 方式 2: 显式加载
var user = await context.Users.FindAsync(1);
await context.Entry(user)
    .Reference(u => u.Profile)
    .LoadAsync();

// 方式 3: 投影查询(推荐)
var userData = await context.Users
    .Where(u => u.Id == 1)
    .Select(u => new 
    {
        u.Username,
        u.Email,
        ProfileBio = u.Profile.Bio,
        ProfileAvatar = u.Profile.Avatar
    })
    .FirstOrDefaultAsync();

场景 2: 创建一对一关系

csharp

// 方式 1: 同时创建
var user = new User 
{ 
    Username = "john",
    Email = "john@example.com",
    Profile = new UserProfile 
    { 
        Bio = "Hello!",
        Avatar = "avatar.jpg"
    }
};

context.Users.Add(user);
await context.SaveChangesAsync();

// 方式 2: 分别创建
var user = new User { Username = "john", Email = "john@example.com" };
context.Users.Add(user);
await context.SaveChangesAsync();  // 先生成 User.Id

var profile = new UserProfile 
{ 
    UserId = user.Id,  // 使用生成的 ID
    Bio = "Hello!",
    Avatar = "avatar.jpg"
};
context.UserProfiles.Add(profile);
await context.SaveChangesAsync();

场景 3: 更新一对一关系

csharp

// 更新配置文件
var user = await context.Users
    .Include(u => u.Profile)
    .FirstOrDefaultAsync(u => u.Id == 1);

if (user.Profile == null)
{
    // 创建新配置文件
    user.Profile = new UserProfile 
    { 
        Bio = "New bio",
        Avatar = "new.jpg"
    };
}
else
{
    // 更新现有配置文件
    user.Profile.Bio = "Updated bio";
    user.Profile.Avatar = "updated.jpg";
}

await context.SaveChangesAsync();

场景 4: 删除一对一关系

csharp

// 删除配置文件但保留用户
var user = await context.Users
    .Include(u => u.Profile)
    .FirstOrDefaultAsync(u => u.Id == 1);

if (user.Profile != null)
{
    context.UserProfiles.Remove(user.Profile);
    await context.SaveChangesAsync();
}

// 删除用户(级联删除配置文件)
context.Users.Remove(user);
await context.SaveChangesAsync();

场景 5: 检查关系是否存在

csharp

// 检查用户是否有配置文件
var hasProfile = await context.Users
    .AnyAsync(u => u.Id == 1 && u.Profile != null);

// 或者
var user = await context.Users
    .Include(u => u.Profile)
    .FirstOrDefaultAsync(u => u.Id == 1);

bool hasProfile = user?.Profile != null;

.NET 8/9/10 新特性

.NET 8: 改进的导航属性初始化

csharp

// .NET 8 更好地处理导航属性初始化
public class User
{
    public int Id { get; set; }
    public string Username { get; set; }
    
    // 可以安全地初始化
    public UserProfile Profile { get; set; } = new();
}

// EF Core 8 正确处理初始化的导航属性

.NET 9: 增强的关系诊断

csharp

builder.Services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(connectionString)
           .EnableDetailedErrors()
           .LogTo(Console.WriteLine, LogLevel.Debug);
});

// .NET 9 提供更详细的关系配置诊断
// info: Configuring one-to-one relationship between 'User' and 'UserProfile'
// info: Foreign key: UserProfile.UserId → User.Id

.NET 10: 智能关系优化(路线图)

预计特性:

自动检测关系配置问题
基于访问模式的关系加载优化
关系映射性能分析工具

最佳实践与陷阱

最佳实践

1. 优先使用共享主键

csharp

// ✅ 推荐: 共享主键(严格一对一)
modelBuilder.Entity<User>()
    .HasOne(u => u.Profile)
    .WithOne(p => p.User)
    .HasForeignKey<UserProfile>(p => p.Id);

// 优点:
// - 节省空间
// - 保证严格一对一
// - 查询性能好

2. 为外键创建索引

csharp

// ✅ 推荐: 即使是一对一外键也创建索引
modelBuilder.Entity<UserProfile>()
    .HasIndex(p => p.UserId)
    .IsUnique();  // 唯一索引

// 提升 JOIN 查询性能

3. 使用 Include 加载

csharp

// ✅ 推荐: 明确指定加载
var user = await context.Users
    .Include(u => u.Profile)
    .FirstOrDefaultAsync(u => u.Id == id);

// ❌ 避免: 延迟加载(除非确实需要)
var user = await context.Users.FindAsync(id);
var profile = user.Profile;  // N+1 查询

4. 验证关系完整性

csharp

// ✅ 推荐: 在业务层验证
public async Task CreateUserWithProfileAsync(User user, UserProfile profile)
{
    // 验证
    if (user == null) throw new ArgumentNullException(nameof(user));
    if (profile == null) throw new ArgumentNullException(nameof(profile));
    
    // 确保一致性
    user.Profile = profile;
    profile.User = user;
    
    context.Users.Add(user);
    await context.SaveChangesAsync();
}

常见陷阱

陷阱 1: 循环引用

csharp

// ❌ 错误: JSON 序列化时循环引用
var user = await context.Users
    .Include(u => u.Profile)
    .FirstOrDefaultAsync(u => u.Id == 1);

return Results.Json(user);  
// 💥 StackOverflowException: User → Profile → User → ...

// ✅ 解决: 使用 DTO
var userDto = new UserDto
{
    Id = user.Id,
    Username = user.Username,
    ProfileBio = user.Profile?.Bio,
    ProfileAvatar = user.Profile?.Avatar
};
return Results.Json(userDto);

陷阱 2: 忘记 Include

csharp

// ❌ 错误: 访问未加载的导航属性
var user = await context.Users.FindAsync(1);
var bio = user.Profile.Bio;  // 💥 NullReferenceException!

// ✅ 正确: Include 加载
var user = await context.Users
    .Include(u => u.Profile)
    .FirstOrDefaultAsync(u => u.Id == 1);

陷阱 3: 错误的级联删除

csharp

// ❌ 错误: 两个都配置 Cascade,导致循环级联
modelBuilder.Entity<User>()
    .HasOne(u => u.Profile)
    .WithOne(p => p.User)
    .HasForeignKey<UserProfile>(p => p.UserId)
    .OnDelete(DeleteBehavior.Cascade);

// 如果还有其他关系可能导致冲突
// SQL Server: "Introducing FOREIGN KEY constraint may cause cycles"

// ✅ 解决: 一端 Cascade,另一端 Restrict

陷阱 4: 可选关系误用

csharp

// ❌ 错误: 应该是必需关系却用了可选
public class UserProfile
{
    public int? UserId { get; set; }  // 💥 允许 NULL,不符合业务逻辑
}

// ✅ 正确: 配置文件必须属于用户
public class UserProfile
{
    public int UserId { get; set; }  // 非可空
}

性能优化

1. 避免不必要的 Include

csharp

// ❌ 错误: 不需要 Profile 时也 Include
var users = await context.Users
    .Include(u => u.Profile)  // 💥 浪费
    .ToListAsync();

// ✅ 正确: 按需加载
var users = await context.Users.ToListAsync();

// 需要时再 Include
var usersWithProfiles = await context.Users
    .Include(u => u.Profile)
    .ToListAsync();

2. 使用投影查询

csharp

// ✅✅ 最佳: 只查询需要的字段
var userSummaries = await context.Users
    .Select(u => new UserSummaryDto
    {
        Id = u.Id,
        Username = u.Username,
        HasProfile = u.Profile != null,
        Avatar = u.Profile.Avatar
    })
    .ToListAsync();

// 单次查询,无 JOIN 膨胀

总结

核心要点

一对一关系: 使用 HasOne().WithOne()
外键位置: 通常在从表中
共享主键: 最严格的一对一实现
级联删除: 默认 Cascade,根据需求调整
加载策略: Include 预加载或投影查询

配置模板

csharp

// 标准模板: 一对一关系
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<PrincipalEntity>()
        .HasOne(p => p.DependentEntity)
        .WithOne(d => d.PrincipalEntity)
        .HasForeignKey<DependentEntity>(d => d.PrincipalId)
        .OnDelete(DeleteBehavior.Cascade);
}

决策流程

是否需要一对一关系?
├─ 是 → 选择外键策略
│   ├─ 共享主键 → 最严格,节省空间
│   └─ 独立外键 → 更灵活
├─ 是否必需关系?
│   ├─ 是 → 外键非可空
│   └─ 否 → 外键可空
└─ 删除行为?
    ├─ 自动删除 → Cascade
    ├─ 阻止删除 → Restrict
    └─ 保留从实体 → SetNull

下一步

📖 阅读多对多关系配置
🔧 学习继承映射策略
🚀 了解 Owned Entities

一对一关系配置 One-to-One ​

目录 ​

一对一关系基础 ​

概念理解 ​

数据库实现 ​

EF Core 约定 ​

配置方式详解 ​

方法 1: Fluent API(推荐) ​

方法 2: 必需关系 vs 可选关系 ​

必需关系(Required) ​

可选关系(Optional) ​

方法 3: 共享主键(Shared Primary Key) ​

方法 4: 数据注解 ​

级联删除行为 ​

DeleteBehavior 选项 ​

1. Cascade(级联删除) ​

2. Restrict(限制删除) ​

3. SetNull(设为 NULL) ​

4. ClientSetNull(客户端设 NULL) ​

级联删除对比表 ​

高级应用场景 ​

场景 1: 加载一对一关系 ​

场景 2: 创建一对一关系 ​

场景 3: 更新一对一关系 ​

场景 4: 删除一对一关系 ​

场景 5: 检查关系是否存在 ​

.NET 8/9/10 新特性 ​

.NET 8: 改进的导航属性初始化 ​

.NET 9: 增强的关系诊断 ​

.NET 10: 智能关系优化(路线图) ​

最佳实践与陷阱 ​

最佳实践 ​

1. 优先使用共享主键 ​

2. 为外键创建索引 ​

3. 使用 Include 加载 ​

4. 验证关系完整性 ​

常见陷阱 ​

陷阱 1: 循环引用 ​

陷阱 2: 忘记 Include ​

陷阱 3: 错误的级联删除 ​

陷阱 4: 可选关系误用 ​

性能优化 ​

1. 避免不必要的 Include ​

2. 使用投影查询 ​

总结 ​

核心要点 ​

配置模板 ​

决策流程 ​

下一步 ​

一对一关系配置 One-to-One

目录

一对一关系基础

概念理解

数据库实现

EF Core 约定

配置方式详解

方法 1: Fluent API(推荐)

方法 2: 必需关系 vs 可选关系

必需关系(Required)

可选关系(Optional)

方法 3: 共享主键(Shared Primary Key)

方法 4: 数据注解

级联删除行为

DeleteBehavior 选项

1. Cascade(级联删除)

2. Restrict(限制删除)

3. SetNull(设为 NULL)

4. ClientSetNull(客户端设 NULL)

级联删除对比表

高级应用场景

场景 1: 加载一对一关系

场景 2: 创建一对一关系

场景 3: 更新一对一关系

场景 4: 删除一对一关系

场景 5: 检查关系是否存在

.NET 8/9/10 新特性

.NET 8: 改进的导航属性初始化

.NET 9: 增强的关系诊断

.NET 10: 智能关系优化(路线图)

最佳实践与陷阱

最佳实践

1. 优先使用共享主键

2. 为外键创建索引

3. 使用 Include 加载

4. 验证关系完整性

常见陷阱

陷阱 1: 循环引用

陷阱 2: 忘记 Include

陷阱 3: 错误的级联删除

陷阱 4: 可选关系误用

性能优化

1. 避免不必要的 Include

2. 使用投影查询

总结

核心要点

配置模板

决策流程

下一步