声明与模型构建
实体怎么标、键怎么定、表列怎么映射、声明词汇全集、配置类与手写覆盖的优先序。 上位:总览。
实体注册与上下文绑定
[EfEntity("Billing", EfEntityFeatures.FullAudited | EfEntityFeatures.SoftDelete)]
public sealed class Invoice { ... }
三种绑定形态([EfEntity] 多标注 = 多上下文,n:n 绑定):
| 形态 | 写法 | 依赖含义 |
|---|---|---|
| 名称绑定(推荐) | [EfEntity("Billing")] |
实体程序集零依赖——不引用上下文类型、不引任何 EF Core 包,只有 KernLab.Loom.Abstractions 一个引用;名称在生成期解析到唯一/指定上下文 |
| 类型绑定 | [EfEntity(typeof(Billing))] |
实体编译需要看到上下文类型——上下文与实体同程序集、或实体程序集愿意引用宿主时用;无额外能力差异 |
| 无参跟随 | [EfEntity(features)] / [EfEntity()] |
跟随程序集内唯一上下文(多上下文 = 歧义 KLSG202 编译报错) |
依赖铁律:名称形态下,实体程序集对 EF Core 的依赖是零——EF 只出现在宿主程序集(引用 KernLab.Loom.Ef.Runtime 的那个)。领域模型层可以纯净地只依赖 Abstractions,把 EF 的完整上下文包挡在组合根。
上下文三种声明形态与依赖落位
EF Core 应该落在哪一层是架构选择——三种形态逐级降低上下文声明面的依赖:
| 形态 | 声明写法 | 声明面需要的引用 | EF Core 落位 |
|---|---|---|---|
| 壳声明(推荐) | public sealed partial class AppDbContext : ILoomDbContext, ITenantAwareContext { } |
仅 Abstractions——ILoomDbContext/ITenantAwareContext 都是零成员标记接口,住在 Abstractions |
生成物补全部件发射 LoomDbContext 基类、机械接口与 options 构造器(壳未声明任何构造函数时自动补齐);EF 引用最终落在组合根(AddLoomEf 处) |
| 手写继承 | public sealed partial class AppDbContext : LoomDbContext, ITenantAwareContext { ... } |
Abstractions + Ef.Runtime | 声明面直接拖运行时包——上下文与组合根同程序集时的省事形态 |
| 全生成(自动创建) | 不写上下文——只在实体上 [EfEntity("AppDbContext", ...)] |
仅 Abstractions | 名称绑定无匹配 = 生成器整体生成上下文类(DbSet/配置/构造器全套,用户后续 partial 补充) |
- 壳的机制:partial 类无主类——业务部分(零基类)与生成部分(带
LoomDbContext基类)平等合并;ILoomDbContext永不加成员(防实现者连环破坏),UoW/主从等能力以派生接口承接(ILoomUowParticipant : ILoomDbContext)。 - 租户约定同步零依赖:
ITenantAwareContext同样住在 Abstractions——壳声明 + 租户配对锁(KLSG201)全程不碰 EF。 - 绑定目标合法性:
[EfEntity]的绑定目标实现ILoomDbContext即合法(不必派生 DbContext);误绑两者皆非者 KLSG203 编译报错。
| 标注 / 接口 | 位置 | 物化 |
|---|---|---|
[EfEntity(ctx, features)] |
实体类 | 注册 + 全套物化(三形态见上表) |
[EfKey(Order = n)] |
属性 | 主键识别(组合键 1..N 连续);EfKeyStrategy:Snowflake/Identity/Explicit |
ILoomDbContext |
上下文 | 零知识壳声明——生成物补 LoomDbContext 基类与机械(见形态表) |
ICreationAudited 族(5 标记接口) |
实体类 | 审计特征位的按口选修形态——实现哪个补哪族字段,不必上 FullAudited |
IEntityTypeConfiguration<T> |
配置类 | 配置类直载——与 [EfEntity] 同被生成器收集,按序物化进 LoomConfigure |
上下文绑定错误即编译错误:绑定目标非 DbContext(KLSG203)、多上下文歧义(KLSG202)、引用程序集上下文不可合并(KLSG208)、租户实体落入未挂租户约定的上下文(KLSG201——配对锁,详见多租户与身份基座)。名称绑定无匹配 = 生成上下文类(不是错误)。
n:n 多绑定:同一实体 [EfEntity(typeof(WriteCtx))] + [EfEntity(typeof(ReadCtx))] 分别入两个上下文——读写分离的双上下文形态(主从读写分离)与模块化各自建模都靠它;每个上下文各发一套 OnModelCreating 配置。
键策略与雪花赋值时点
EfKeyStrategy 三档:Snowflake(缺省经 ID 缝赋值)/ Identity(数据库自增)/ Explicit(业务自赋)。
雪花键赋值时点(挂起多加):雪花键 ValueGeneratedNever,缺省在 SaveChanges 时经 ID 缝赋值——同上下文未赋键挂起多加(Add/AddRange 后一次保存)会撞 EF 主键冲突。正解 = 构造器/创建处赋真键(微软对客户端生成键的官方模式):
// 形态一(推荐):静态号源——实体构造器自足,挂起多加天然可用
public sealed class Order
{
public long Id { get; set; } = LoomSnowflakeIdGenerator.Shared.NewId(); // WorkerId=0 进程级号源
}
db.Orders.AddRange(order1, order2); // 键各异零冲突
await db.SaveChangesAsync();
// 形态二:容器缝注入(集群租约 workerId 等血统场景)
public sealed class OrderService(ILoomIdGenerator snowflake)
{
public Order Create(string title) => new() { Id = snowflake.NewId(), Title = title };
}
// 形态三(#81):批量预赋键——实体已创建、批量入库前统一补键
LoomSnowflakeIdGenerator.BatchAssign(orders, e => e.Id, (e, id) => e.Id = id); // 仅补 Id==0 的实体
db.Orders.AddRange(orders);
await db.SaveChangesAsync();
★ 最重要使用税(#81):
db.Set<T>().AddRange(a, b); SaveChanges()是反模式——雪花键ValueGeneratedNever, Add 时键=0,EF identity map 以 0 入槽,第二行即ThrowIdentityConflict(连 TPH 不同派生也炸)。 批量插入必须预赋键:构造器赋值(形态一)/ ID 缝(形态二)/BatchAssign(形态三)三选一。
批量插入官方形态(#149/#150):
await db.LoomBulkInsertAsync(rows, chunkSize: 1000)——自动预赋雪花键 (单键 long;显式键尊重)、分块、事务原子(无环境事务时自建,UoW 内加入外层事务)、逐块SaveChanges; 审计/watch/校验/提交门/租户/拦截器全部保留。分块大小控制单次 SaveChanges 与跟踪器增长,不改变逐行 INSERT 成本(SQLite 每行一条,SQL Server 受MaxBatchSize批处理)。SqlBulkCopy/COPY 级吞吐不内建—— 那会绕过治理管线(架构职责边界,不是静默缺失);需要时用 provider 原生 bulk API 并显式自担审计/watch/ 提交门/租户执法旁路。可测边界:LoomBulkInsertBehaviorTests(26 行 = 26 条 INSERT / 3 次 SaveChanges)、 基准ManagedBulkInsertBench。跟踪器保留已插入实体(键已回填);超大集合可在调用后ChangeTracker.Clear()。
纪律:静态 Shared(WorkerId=0)与容器 DI 实例二选一,不得混用(同 workerId 双实例并号有碰撞风险)。雪花号结构 41/10/12 与时钟回拨守卫见观测·种子·迁移·冻结模型。
表与列:声明词汇全集
表级
| 标注 | 形态 | 物化 |
|---|---|---|
[EfTable("ord_order")] |
实体类 | 显式表名 |
[EfTablePrefix("ord_")] |
实体类 | 前缀_约定名 |
[EfTable("t", Comment = "订单主表")] |
实体类 | 表名 + 表注释(ToTable(t => tb.HasComment(...))) |
[EfTable(Comment = "仅注释")] |
实体类 | 注释-only——表名走 EF 约定 |
[EfInheritance(InheritanceStrategy.Tph)] |
基类实体 | 继承层次映射策略(见继承映射) |
[EfReadOnly] |
实体类 | 实体级只读执法——增删改全 Throw(码表/归档/ETL 目标) |
[assembly: EfNaming(LoomNamingStrategy.SnakeCase)] |
程序集 | 整库表列名转换策略(见命名策略) |
列级——统一列声明 [EfColumn](一特性全信息)
[EfEntity(typeof(UserCtx))]
public sealed class User
{
[EfKey(EfKeyStrategy.Identity)]
public long Id { get; set; }
[EfColumn(Name = "mobile_no", TypeName = "varchar(20)", Required = true, Comment = "手机号")]
public string Mobile { get; set; } = "";
[EfColumn(Precision = 18, Scale = 6, Default = "0", Comment = "汇率")]
public decimal Rate { get; set; }
[EfColumn(DefaultSql = "getdate()", Required = true)]
public DateTime CreatedAt { get; set; }
}
全部命名参数可选,标了才发射;展开为同一条 PropertyBuilder 链(HasColumnType + HasPrecision + HasDefaultValue + IsRequired + HasComment)——与细粒度特性同一发射管线。
| 参数 | 语义 |
|---|---|
Name |
显式列名(缺省 CLR 属性名;存量库列名对齐;显式名永不被命名策略转换) |
TypeName |
列类型直传 provider(char(18)/varchar(20)——Unicode 语义由类型名自带) |
Precision + Scale |
decimal 精度(缺省 decimal(18,2) 不够时用) |
Default |
DB 端常量默认(非 Loom 路径 INSERT 生效;Loom 拦截器填值先于 DB 默认) |
DefaultSql |
DB 端 SQL 默认(与 Default 互斥 = KLSG) |
Required |
true = 非空列;false = 显式可空;未声明 = NRT 推断(现状不变) |
Comment |
列注释 |
选型指引:单维度调整用细粒度特性(下表);整列信息集中声明用统一特性(新表设计/老库对齐——列定义一处可读)。
列级——细粒度与行为特性
| 标注 | 形态 | 物化 / 语义 |
|---|---|---|
[EfPrecision(18, 4)] |
decimal 属性 | .HasPrecision(18, 4);非 decimal = KLSG;scale > precision = KLSG;与 [EfColumn(Precision=)] 双标同维度 = KLSG 二选一 |
[EfDefault("0")] |
属性 | .HasDefaultValue(...);与 [EfDefaultValueSql] 双标 = KLSG |
[EfDefaultValueSql("getdate()")] |
属性 | .HasDefaultValueSql(...) |
[EfComputed("sql", Stored = true)] |
属性 | 持久化计算列(可索引);EF 自动只读;与 [EfWriteOnce]/[EfDefault] 双标 = KLSG |
[EfComment("注释")] |
属性 | .HasComment(...)(列注释专用名,与表注释走 [EfTable(Comment=)] 分域) |
[EfNotMapped] |
属性 | .Ignore(...)——不建列、不进变更追踪/审计/watch/投影全排除(投影域的 [EfIgnore] 是另一个域,不混用) |
[EfWriteOnce] |
属性 | 写一次执法(见下) |
[EfShadow("LegacyRef", typeof(string))] |
实体类 | 业务影子列(列名常量入 LoomColumns.Order.LegacyRef) |
[EfJson] / [EfRowVersion] |
属性 | owned JSON 列 / 行版本(与 Concurrency 特征互斥)——见ComplexType 与 JSON |
[EfUnique("UX_Orders_Email", "Email")] |
实体类 | 唯一索引(见下) |
[EfAuditIgnore] / [EfAuditMask] |
属性 | 操作日志豁免 / 掩码——见审计与操作日志 |
[EfCharSet(EfCharSets.Digits)] |
属性 | 保存校验字符集白名单——见保存路径字段校验 |
共存规则:统一特性与细粒度特性双标同语义维度 = KLSG 冲突(二选一);不同维度正交可叠加([EfColumn] + [EfUnique] + [EfWriteOnce] 三域互不重叠)。显式列名与 [EfShadow] 显式名、[EfAlias] 投影别名三面互不相干(各管各域)。
软删唯一索引 [EfUnique]
软删场景唯一约束(如"租户内邮箱唯一")需要 filter 排除已删行——手写 filter 逐 provider 语法易错:
[EfUnique("UX_Users_Email", nameof(Email))] // 索引名 + 成员列表;可多标多索引
public sealed class User { public string Email { get; set; } = ""; ... }
- 发射
HasIndex(...).IsUnique();成员含影子列允许(列名发射已支持)。 - 软删联动:实体带 SoftDelete 特征 → 唯一索引自动补 HasFilter,filter 文案按发射期 provider 物化(SQLite/PG
IsDeleted = 0、SqlServerIsDeleted = CONVERT([bit], 0))。业务显式HasFilter不覆盖(自动面只补缺)。 - 索引名冲突 = KLSG。
写一次 [EfWriteOnce]
单据号/证件号/注册邮箱——防篡改双级执法:
- 发射
.AfterSaveBehavior(PropertySaveBehavior.Throw)(EF 原生兜底——保存过的实体再改 → Save 抛); - 提交门早拦截:Modified 实体的 write-once 属性
OriginalValue != CurrentValue→ 保存前 Throw 指路(早于 EF、可读、loom_ef_writeonce_reject_total计数)。
Add 首赋值合法(写一次 = 首写自由);key/并发戳属性标注 = KLSG(各有既有语义);受管语句级 LoomUpdateAsync 与原生 ExecuteUpdate(逃逸舱白名单开启形态)同拦——执法层 = SQL 规则解析(命令拦截器执行前解析 UPDATE 的 SET 列集,表名反查实体、write-once 成员经 EF 元数据映射列名,命中 = 拒 + 计数;fail-closed:不认识的 UPDATE 形态拒绝执行)。
生成器:实体配置自动收集
实体配置不需要任何运行时注册——编译期收集,事实直出(ApplyConfigurationsFromAssembly 的反射扫描已退役):
你写 生成器收集 → 物化(增量,改哪补哪) 运行时
───────────────────────────────────── ────────────────────────────────────── ──────────────
[EfEntity(typeof(Billing), FullAudited)] ─→ 逐实体配置行:列计划/键/影子列/过滤器/ OnModelCreating
public class Order { ... } 审计字段/并发戳/JSON 列 → LoomConfigure
class OrderConfig : IEntityTypeConfiguration ─→ 配置类直载序列(物化序) → 约定档
<Order> { ... } → 手写覆盖
- 收集面:
[EfEntity]实体 +IEntityTypeConfiguration<T>配置类同一批收集(增量源生成器——只重算改动节点);多标注 = 同实体入多上下文(n:n 绑定)。 - 物化面:每上下文一个生成文件——
LoomConfigure内是逐实体配置行 + 配置类直载序列(ApplyConfiguration按声明序调用)+ 动态视图ToSqlQuery;另有LoomEfRegistry(描述符清单——监听路由/种子目录/查询注册表的数据源)与LoomColumns(影子列名常量)。
三段式覆盖序(原生兼容的核心)
手写 OnModelCreating 覆盖 (最高——调 base.OnModelCreating 即落中间,EF 惯例)
└─ 配置类直载 (IEntityTypeConfiguration<T> 按声明序)
└─ 生成物 (标注物化的逐实体配置行)
└─ 约定档 (LoomConventionApplier:长度 256/UTC/枚举存储——最后补缺)
全部 EF 原生配置手段(HasConversion 值转换器、导航配置、原生继承/owned type fluent API)在配置类与手写层照旧可用——Loom 不吞不藏。装配位:上下文经 AddLoomEf*(或壳声明 ILoomDbContext 由生成物补基类)接入——零注册零扫描,模型构建即编译期事实的重放。
反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
| 批量 Add 多个雪花键实体后一次保存报主键冲突 | 雪花键 ValueGeneratedNever,保存时才赋值——未赋键挂起多行键同为 0 触发 EF 冲突 | 构造器赋值 LoomSnowflakeIdGenerator.Shared.NewId(),或注入 ID 缝预赋键,或 BatchAssign 批量补键(#81),或逐条 Add+SaveChanges |
| 统一特性与细粒度特性同维度双标 | 同一维度两个声明源——发射合并无法仲裁 | 二选一:单维度用细粒度,整列信息用 [EfColumn] |
| TPH 派生实体配置里重发基类属性 | EF 继承语义:基类属性归基类 builder | 派生只发自有属性(发射器归属核实保证) |
手写 OnModelCreating 忘调 base |
跳过生成物与配置类直载——声明面全部失效 | base.OnModelCreating(modelBuilder) 保留在覆盖首行 |
| 实体改了名直接跑,表列名没变/变了不认识 | 显式名 vs 约定名混用时没意识到谁在生效 | 命名策略上线前后用迁移 diff 核对;显式名搜 [EfTable(/Name = 清点 |
| 码表实体被业务误改/误删 | 无只读声明 | [EfReadOnly] 实体级只读执法(增删改全 Throw) |
上下文声明面直接继承 LoomDbContext,领域契约程序集被拖进 EF |
手写继承形态让声明面引用 Ef.Runtime——依赖落位失控 | 上下文用 ILoomDbContext 壳声明(仅 Abstractions),EF 留在组合根(见「上下文三种声明形态与依赖落位」) |
壳声明里手写 DbContextOptions 构造器又与生成物冲突 |
壳未声明构造器时生成器自动补 options 构造器——双声明冗余 | 壳保持零构造器(要自定义构造逻辑再手写,生成器让位) |
| 汇率/单价小数位被截成两位 | decimal 未声明精度——缺省 decimal(18,2) | [EfPrecision(18, 6)] 或 [EfColumn(Precision = 18, Scale = 6)] |
| 手机号列建成 nvarchar | 未声明列类型——缺省 nvarchar | [EfColumn(TypeName = "varchar(20)")] |
想深入
- 继承层次:继承映射 · 列名整库转换:命名策略
- 值对象存储:ComplexType 与 JSON
- API 参考:docs.kernlab.dev/loom/api