Table of Contents

实体框架

可运行 sample:samples/Ef/App(实体 + LoomDbContext + UoW 增改删)、samples/Query/App(Filterable/DSL)。

定位

KernLab.Loom.EF 是 EF Core 的编译期扩展层:实体上打声明标注,源生成器在编译期物化模型配置、审计、投影、动态视图、监听路由、种子与设计期工厂,运行时零反射;AOT 覆盖模型/初始化面(EF 查询边界见 operations.md)。解决四类问题:手写 OnModelCreating 配置样板、审计/软删/租户/并发等横切列的反复实现、第三方 Mapper 的运行时反射与配置爆炸、复杂 SQL 与即席查询的治理失控。它在 KernLab 家族中是 KernLab.Loom(编译期层)的一张面,与协议/布局/端点/DI 各面同构——声明进编译器,治理自动生效。

EF 版本支持口径

两框架多目标:KernLab.Loom.* 全家族多目标 net8.0;net10.0——EF Core 按腿钉版 (EF 8.0.11 / EF 10.0.13,Directory.Packages.props 按 TFM 求值)。口径(D7 决议):

腿 口径
net8.0 腿(EF 8.0.11) 功能冻结——既有行为回归守卫,不进新功能
net10.0 腿(EF 10.0.13) 新功能落点——全部新面/新特性先落此腿
net9.0 不建(非 LTS,两框架口径下无承载位)

消费方按宿主 TFM 自动取对应腿。AOT 边界两腿分别实测:查询管线 EF8 即就绪; SaveChanges 影子列快照缺口在 EF10 下复测定谳(实测边界见下文 AOT 边界节)。

快速上手

三个包:实体程序集引 KernLab.Loom.Abstractions(零框架拖带);宿主引 KernLab.Loom.Ef.Runtime;KernLab.Loom.Ef 是源生成器(analyzer 形态,引用即生效)。实体与上下文声明都不依赖 EF Core——实体用名称绑定、上下文用 ILoomDbContext 壳声明,EF 只落在最终组合根(调用 AddLoomEf 的那个程序集),见声明与模型构建的形态表:

// ① 实体——声明即治理,未标注不注册;整个程序集只有 Abstractions 一个引用
[EfEntity("AppDbContext",                       // 名称绑定——不引用上下文类型
    EfEntityFeatures.FullAudited | EfEntityFeatures.SoftDelete | EfEntityFeatures.Tenant,
    Key = EfKeyStrategy.Snowflake)]
public sealed class Order
{
    public long Id { get; set; }                                // 雪花键经 ID 缝赋值
    public string OrderNo { get; set; } = "";
    public decimal Amount { get; set; }
    public string ConcurrencyStamp { get; set; } = "";
    // 审计/租户/软删/并发列不声明——影子列由生成物挂载
}

// ② 上下文——壳声明(partial 无主类:该声明零基类零构造器,只有 Abstractions 一个引用;
//    生成物补全部件发射 LoomDbContext 基类、机械接口与 options 构造器)
public sealed partial class AppDbContext : ILoomDbContext, ITenantAwareContext
{
}

// ③ 组合根(引用 Ef.Runtime 的程序集;身份缝/ID 缝由宿主供给,提交门管线自动装配)
var services = new ServiceCollection()
    .AddSingleton<ILoomAuditIdentity>(identity)
    .AddSingleton<ILoomIdGenerator>(snowflake)
    .AddLoomEf<AppDbContext>(o => o.UseSqlServer(connectionString));

// ④ 查询(租户/软删过滤器自动生效)
await using var db = services.GetRequiredService<AppDbContext>();
var open = await db.Orders.Where(o => o.Amount > 100).ToListAsync();

// 装配形态三注入:AddLoomEf(Scoped 上下文)| AddLoomEfFactory(IDbContextFactory——无作用域场景)|
// AddLoomEfPool(池化租约)——选项/拦截器装配逐字段对齐,可混用;outbox/inbox 开关在 loom 回调上

// ⑤ 迁移(无 DI 的设计期由生成的工厂承接,见「观测·种子·迁移·冻结模型」)
await db.CheckAndMigrateAsync();

概念与术语

  • 特征位(EfEntityFeatures):实体的横切能力开关(FullAudited/SoftDelete/Tenant/Concurrency/AuditTrail),与五个标记接口(ICreationAudited 等)等价,双通道并集。特征位决定生成什么:影子列、过滤器、审计快照、并发戳。
  • 影子列:数据库有列、实体不挂属性的列。框架特征列(TenantId/CreatedAt/IsDeleted/ConcurrencyStamp 等)与业务列([EfShadow])都由生成物挂载,列名常量入 LoomColumns 类。
  • 缝:运行时行为由宿主供给的接口决定——身份缝 ILoomAuditIdentity(审计与租户来源)、ID 缝 ILoomIdGenerator(雪花键)、时钟缝 TimeProvider、审计外发缝 ILoomAuditTrailSink。缝未注册走缺省安全语义:审计记 system、租户写入显式拒绝、雪花键显式异常。全部扩展点清单见 SPI 扩展点。
  • 提交门:保存/提交后的三消费者派发点——审计外发 → 监听路由 → 业务事务钩子(OnCommit/OnRollback)。同步保存走后台派发(不阻塞调用线程),异步保存内联 await。
  • 受管面与逃逸舱:受管 API(LoomUpdateAsync 等)缺省可用、框架强制补谓词与审计;原生逃逸口(ExecuteDelete*/IgnoreQueryFilters 等)缺省禁用(编译期 KLSG214/KLSG211 警告 + 运行时 Throw),白名单显式开启后放行。
  • 设计期工厂:dotnet ef 工具无 DI,生成器为每个上下文发射 IDesignTimeDbContextFactory 缺省实现,产物以系统身份运行(审计记 system)。

怎么选

方案 优势 代价 适用场景
Loom.EF 模型/审计/投影零样板;编译期校验(拼写/租户/有损转换);零反射、AOT 模型/初始化面就绪(查询边界见 operations.md);治理自动生效 声明标注学习面;生成器进编译 新业务;要审计/租户/软删横切一致性的服务
手写 EF Core 零学习面;完全手工控制 配置样板全手写;横切语义靠纪律;无编译期防护 已有稳定 EF 资产且无横切诉求
第三方 Mapper(AutoMapper/Mapster 类) 成熟生态 运行时反射/表达式编译;投影 SQL 残缺;配置爆炸 非持久化场景的内存对象映射

决策:要租户/审计/软删/并发一致性,或投影下推到 SQL 端,选 Loom.EF;存量 EF 资产无横切诉求维持手写;纯内存对象映射用第三方 Mapper(Loom 投影的输入侧 ToEntity/ApplyFrom 只覆盖持久化往返)。

原生兼容(与 EF Core 的关系)

Loom.EF 不包裹、不替代 EF Core——它是发射 EF 原生 typed API 的编译期前端。兼容边界一次说清:

  • 全部 EF 原生能力照旧可用:LINQ 查询、Include/导航、原生 SQL、迁移工具链(dotnet ef migrations)、连接池、IEntityTypeConfiguration<T> 配置类(直载进生成管线,与标注同批收集)。
  • 发射物 = EF 原生调用:生成器发射 ToTable/HasColumnName/HasIndex/HasDiscriminator 等 typed API,无自定义运行时模型层——EF 升级语义即 Loom 语义;产物入库可评审(见 声明与模型构建 的三段式覆盖序)。
  • 手写覆盖永远最高优先:手写 OnModelCreating > 配置类 > 生成物 > 约定档——逃生通道常开,不做黑箱。
  • Provider 面:Sqlite / SqlServer / Npgsql 三线在测;provider 特定行为(软删 filter 文案、JSON 函数翻译)在对应主题页标注。
  • 运行时零反射:模型构建 = 编译期事实重放;配合冻结模型(loom ef optimize)覆盖 AOT 模型/初始化面(查询边界见 观测·种子·迁移·冻结模型)。

文档地图

主题 页 回答什么问题
持久化主线 persistence.md 从最小服务到可上线持久化的决策链:上下文形态/UoW/键策略/建库/审计租户/AOT 边界
声明与模型构建 declarations.md 实体/键/表/列怎么标;声明词汇全集;配置类与手写覆盖
查询与投影 querying.md 过滤器族/影子列/分页/投影映射/动态视图/受管批操作/批量插入
查询规则引擎 query-rules.md 动态条件怎么安全下推 SQL;白名单/复杂度护栏
查询字段目录 field-catalog.html [Filterable] 白名单目录;AST/DSL 双语法;复杂度上限
二级缓存 caching.md 查询级缓存:SPI/失效协议/分布式替换/边界
ComplexType 与 JSON complex-json.md 值对象多列 vs JSON 列怎么选;JSON 查询三层
继承映射 inheritance.md Tph/Tpt/Tpc 三策略声明与边界
命名策略 naming.md 表列名 PascalCase → snake_case 整库转换
多租户与身份基座 multi-tenancy.md 租户隔离怎么声明;身份从哪来
审计与操作日志 auditing.md 审计列/操作日志/掩码/外发缝
保存路径字段校验 validation.md 数据质量值域执法(EF 保存校验真空的补位)
主从读写分离 read-write-split.md 读走从库写走主库;故障转移与粘性窗
工作单元(UoW) ef-usage.md 跨上下文工作单元;参与者;两段式提交
工作单元与消息面 messaging.md 跨上下文本地事务;outbox/inbox/清理
监听路由与消费完整性 watch.md 实体变更监听;六缝消费保障;Outbox 桥
观测·种子·迁移·冻结模型 operations.md 慢 SQL/长事务观测;种子;设计期;AOT 冻结模型
SPI 扩展点 spi.md 全部缝接口:职责/缺省实现/替换方式
枚举显示名 enum-display.html [EnumDisplay] 标注;culture 回退链;零反射
配置参考 configuration.md LoomEfOptions 全键表
Provider 支持矩阵 provider-matrix.html Sqlite/SqlServer/Npgsql 三线逐格验证状态

想深入