OnModelCreating 是 EF Core 模型配置的统一入口,必须在自定义 DbContext 中重写并调用 base.OnModelCreating;通过 ModelBuilder 使用 Fluent API 配置实体映射、关系、索引、种子数据等,顺序无关但建议按逻辑分组;部分简单配置可用数据注解替代,但复杂场景必须依赖 Fluent API。

OnModelCreating 是 EF Core 模型配置的统一入口,所有通过 Fluent API 进行的实体映射、关系定义、索引、种子数据等配置,都必须在这个方法里完成。它在 DbContext 初始化模型时被自动调用一次,只执行一次,不参与运行时查询。
必须重写并调用 base.OnModelCreating
你需要在自定义的 DbContext 类中重写该方法,并显式调用 base.OnModelCreating(modelBuilder),否则部分默认约定或提供程序扩展(如 Identity、达梦适配器)可能失效。
- 不调用 base 可能导致主键推断失败、序列未注册、或某些数据库特有配置丢失
- 即使你只配关系,也建议保留这行——它是安全兜底
核心用途:用 ModelBuilder 配置模型
ModelBuilder 是 Fluent API 的操作主体,它提供链式方法对实体、属性、关系等进行声明式配置。常见场景包括:
- 表名与列名映射:ToTable("blogs")、HasColumnName("blog_id")
- 主键与键约束:HasKey(e => e.Id)、HasAlternateKey(e => e.Code)
- 关系定义:HasOne/HasMany + WithOne/WithMany + HasForeignKey
- 索引与唯一约束:HasIndex(e => e.Email).IsUnique()
- 种子数据:HasData(new Blog { Id = 1, Name = "EF Core 入门" })
- 值生成策略:ValueGeneratedOnAdd()、UseIdentityColumn()
配置顺序不影响最终结果
Fluent API 的调用顺序没有强制依赖。比如先配外键再配关系,或先设索引再设主键,EF Core 内部会统一解析成逻辑一致的模型。但为可读性,建议按“实体 → 属性 → 关系 → 索引 → 种子数据”分组组织代码。
- 同一个实体的配置尽量集中,避免分散在多处
- 跨实体关系(如一对多)只需在一方配置即可,另一方可省略 .WithOne/.WithMany 的 lambda 表达式
- 若使用 IEntityTypeConfiguration 分离配置,仍需在 OnModelCreating 中调用 modelBuilder.ApplyConfigurationsFromAssembly(...)
不是所有配置都必须写在这里
部分简单映射可用数据注解替代,比如 [Table("users")]、[Column("user_name")]、[Index(nameof(Email), IsUnique = true)]。但注解能力有限:
- 无法配置复杂关系(如多对多中间实体的外键方向)
- 不支持条件索引、计算列、序列、删除行为等高级特性
- 复合主键、阴影属性、拥有的实体类型只能用 Fluent API
基本上就这些。OnModelCreating 不是魔法,它只是把你的意图翻译成 EF Core 能理解的元数据模型——写得清楚,迁移才准,运行才稳。










