实体框架
可运行 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 三线逐格验证状态 |
想深入
- API 参考:docs.kernlab.dev/loom/api(docfx 生成)。
- 诊断 ID 全家族注册表:kernlab-dev/.github RULES.md(段位归属与
.editorconfig配置方式)。 - 快速上手(非 EF 面):站点快速上手。