Table of Contents

声明与模型构建

实体怎么标、键怎么定、表列怎么映射、声明词汇全集、配置类与手写覆盖的优先序。 上位:总览。

实体注册与上下文绑定

[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、SqlServer IsDeleted = CONVERT([bit], 0))。业务显式 HasFilter 不覆盖(自动面只补缺)。
  • 索引名冲突 = KLSG。

写一次 [EfWriteOnce]

单据号/证件号/注册邮箱——防篡改双级执法:

  1. 发射 .AfterSaveBehavior(PropertySaveBehavior.Throw)(EF 原生兜底——保存过的实体再改 → Save 抛);
  2. 提交门早拦截: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)")]

想深入