Table of Contents

观测·种子·迁移·冻结模型

慢 SQL/长事务/连接观测、种子框架、设计期与迁移、冻结模型(CompiledModel)与 AOT。 上位:总览。

观测面

缺省即开:慢命令(>1s)、长事务(>10s)、空闲事务(>30s,扫秒器)、慢连接(Open >2s)——警告日志 + loom_ef_* 指标(System.Diagnostics.Metrics)+ LoomEfOptions 回调(OnSlowCommand/OnLongTransaction/OnSlowConnection,缺省 null 零开销)。

计数器族 覆盖
loom_ef_slow_command_total / loom_ef_command_failed_total 慢命令 / 失败命令
loom_ef_long_transaction_total / loom_ef_idle_transaction_total 长事务 / open-but-idle(锁被白白持有的第一时间可见)
loom_ef_connection_open_total / loom_ef_connection_fail_total 连接开设/失败(池耗尽/争用信号)
loom_ef_uow_* / loom_ef_outbox_* / loom_ef_inbox_* UoW 与消息面(工作单元与消息面)
loom_ef_watch_* / loom_ef_audit_* / loom_ef_readsplit_* / loom_ef_writeonce_reject_total / loom_ef_query_memory_total 监听/审计/读写分离/写一次拒绝/JSON 内存模式(各自主题页)
loom_ef_change_sink_fail_total / loom_ef_snapshot_fail_total / loom_ef_tx_hook_fail_total / loom_ef_query_guard_warn_total 提交门副作用分账(#220)——变更流/快照/参与者钩子失败与查询护栏 Warn 不混入 loom_ef_watch_fail_total

阈值全部可调(SlowCommandThreshold 等,见配置参考);空闲扫秒惰性启动——无活动事务零定时器。

种子

[EfSeed(Order = 1, Version = "1.0")]
public class RegionSeed : ILoomSeedProvider
{
    public string SeedKey => "regions";
    public ValueTask SeedAsync(DbContext db, CancellationToken ct) { ... }
}

await db.SeedAsync();   // __loom_seeds 幂等记账;失败即启动失败

AutoSeed 托管服务缺省关(多实例竞态诚实边界)——多实例部署显式控制种子时点,单实例可开。

设计期与迁移

dotnet ef migrations add 无 DI:生成器为每个上下文发射 IDesignTimeDbContextFactory 缺省实现。连串解析序:--connection 参数 → LOOM_{上下文名大写下蛇形}_CONNECTION 环境变量 → 占位串;provider 按编译引用面自动物化(Sqlite/SqlServer/Npgsql)。工厂产物以系统身份运行(审计记 system)。自带工厂的上下文生成器不发射——同上下文双工厂会被 EF tools 拒绝。

运行期迁移与种子:

await db.CheckAndMigrateAsync();   // 有迁移走迁移,无迁移 EnsureCreated 兜底
await db.SeedAsync();

迁移产物形态:bundle / idempotent 脚本 / CI 出包(后置定案,2026-10-19,#149)

定案:1.x 不新增迁移产物工具面;常规部署由现有 CheckAndMigrateAsync + 设计期工厂覆盖。 可审计证据:src/KernLab.Loom.Ef.Runtime/Seed/LoomSeedExtensions.cs:23-33(未应用迁移 → MigrateAsync; 无迁移体 → EnsureCreatedAsync 幂等兜底)、src/KernLab.Loom.Ef/EfDesignTimeFactoryEmitter.cs(逐上下文 IDesignTimeDbContextFactory,dotnet ef migrations add 无 DI 可用)、 tests/KernLab.Loom.Ef.Tests/EfDesignTimeFactoryTests.cs:61(工厂接口形态断言)。

后置项 状态 理由 触发条件
dotnet ef migrations bundle(自包含迁移可执行件) 不包装 上游标准命令,消费者可直接对 Loom 生成的设计期工厂运行;Loom 包装只增加版本耦合 需离线/无 SDK 环境部署且现有 MigrateAsync 路径不可用时,评估 loom ef migrations bundle 薄封装
dotnet ef migrations script --idempotent 不包装 同上——标准 EF 命令;脚本审阅属 DBA/发布流程,不进运行时库 受监管环境要求脚本留档/审批;先在消费仓 CI 生成并入库
CI 出包(迁移脚本作为发布产物) 不做 Loom 发布管线只产 NuGet/文档;数据库变更节奏与库版本解耦是消费方部署责任 多环境(dev/test/uat/prd)需要同源迁移产物时,由消费方 CI 调用标准 EF 命令并归档

边界:CheckAndMigrateAsync 是运行期便利帮手(有迁移走迁移、无迁移建库),不是部署编排器; 多实例并发首启仍应单点执行迁移(与 AutoSeed 同款竞态边界)。迁移 bundle/脚本的生成时机、审批与回滚 归消费方发布流程——Loom 不接管。AOT 注解:本方法标 [RequiresDynamicCode]/[RequiresUnreferencedCode] (EF 迁移/EnsureCreated 依赖设计期模型)——NativeAOT 下改用 migration bundle 或预先 DDL,与 EnsureCreated 边界同源。

雪花 ID(41/10/12)

// 缺省:new 即用(workerId=0——单机形态)
services.AddSingleton<ILoomIdGenerator>(new LoomSnowflakeIdGenerator());

// 集群形态:租约轮换(每次生成前解析 workerId,轮换即换核心——序列不碰撞)
public sealed class LeaseSnowflakeGenerator(WorkerLease lease) : LoomSnowflakeIdGeneratorBase()
{
    protected override long ResolveWorkerId() => lease.CurrentWorkerId;   // 0-1023
}

时钟回拨两档守卫(守卫窗内等待追平、超窗确定性抛出——静默续发=重复键不可接受);workerId 越界构造即抛。赋值时点与挂起多加纪律见声明与模型构建。

冻结模型(CompiledModel——AOT/启动加速,opt-in)

模型从运行时反射构建搬进编译期代码:loom ef optimize 产出全部上下文的冻结模型 + Loom 接线文件,运行时逐上下文 opt-in。三步:

# ① 装工具
dotnet tool install KernLab.Loom.Tools
# ② 产出冻结模型(产物入库可评审;自动注入冻结期旗标——查询过滤器发射跳过,接线文件 Customize 缝重挂)
loom ef optimize --project src/App --provider Sqlite
# ③ 运行时逐上下文 opt-in(未 optimize 即开启 = fail-fast 指路)
services.AddLoomEf<AppDbContext>(o => o.UseSqlServer(cs), loom => loom.CompiledModel = true);

查询预编译(PCQ)边界(#148):--precompile-queries / --nativeaot 旗标已为 EF10+ 查询计划冻结预留, 但上游 CS9270(EF 生成器旧式 [InterceptsLocation],dotnet/efcore#35483)未解除前显式失败(退出码 3)—— 不转调、不产出半成品、不静默降级。当前冻结模型只覆盖模型面;查询面 AOT 仍如实报 boundary=ef10-precompiled-required。解除后按仓内 docs/design/precompiled-queries-design.md §5-7 全量落地。

收益:模型构建消失(首查提速);AOT 真编译真运行覆盖模型/初始化面(冻结模型注册/构建/指纹/DI/DDL), 查询面按下方 EF8/EF10 边界。防漂移卡点 = 三闸: ① 编译期形状告警(KLSG242)——optimize 产物成员集缺当前实体映射成员时 dotnet build 即 Warning (改了实体没重跑 optimize,不再等到宿主启动); ② 模型指纹(模型型选项 9 键 + provider + Loom/EF 版本)——运行时选项与 optimize 时点漂移即 fail-fast; ③ 实体形状(编译期映射成员清单 vs 冻结模型逐实体比对)——上下文构建期即抛"冻结模型过期"并列出 缺失的 实体.成员(不会拖到插入时爆 NOT NULL)。

同源纪律:模型型选项是构建期常量性质——推荐写成静态同源方法(AddLoomEf 与设计期共用)。缺省选项直接 loom ef optimize;非缺省选项用同源方法 LoomCompiledModelFingerprint.Compute(AppDbConfig.LoomOptions, "SqlServer") 自算后 --fingerprint 0x… 回填(CLI 不解析选项值)。

与各扩展的兼容:读写分离路由在命令层(模型不变,全兼容);命名策略发射期物化(产物名字已固化,天然一致);主从/ComplexType/继承映射均为 typed API 发射(optimize 自检为准)。

EF8/EF10 查询边界(实测):AOT 下冻结模型覆盖模型/初始化面(冻结模型、注册、指纹、DI、DDL); EF8 查询物化唯一路径是 Expression.Compile(),真 AOT 被上游拒绝(probe 断言 boundary=ef8-query); EF10 查询需设计期 precompiled queries(当前离线:CS9270,probe 断言 boundary=ef10-precompiled-required)。 SaveChanges 影子列实体的快照工厂同属上游 NativeAotNoCompiledModel 边界;EnsureCreated 走设计期模型同被拒—— 建库面用入仓 DDL 或迁移脚本。JIT(非 AOT)下冻结模型全链可用(含 SaveChanges/拦截器族,行为矩阵为证)。

容器级绑定注册表(#227 P2——AOT/多容器)

LoomEfOptions.BindingRegistry 注入容器级 LoomBindingRegistry 后,枚举字符串转换器(EnumStorage.String) 的查表顺序为:容器 registry(须 Freeze)→ 进程静态表(生成器兼容桥)→ AOT fail-fast / JIT 反射回退。

  • 注入即扇出:AddLoomEf/AddLoomEfFactory/AddLoomEfPool 自动把生成器登记的绑定写入 registry (LoomEfBindingRegistrarCatalog——生成物 ModuleInitializer 自登记;幂等重注册 no-op)。
  • 多容器隔离:各 AddLoomEf 一套 registry,测试替身/租户可注册不同实现(进程静态表做不到)。
  • Freeze 责任在组合根:注册完成后 registry.Freeze();未冻结时查表面自动走静态表兜底(现状行为)。
  • 启动校验:LoomBindingValidator.ValidateOrThrow(registry, LoomEfBindingRegistrarCatalog.AggregateManifest(), LoomBindingMode.Aot, !RuntimeFeature.IsDynamicCodeSupported)——必需绑定缺失 = 启动失败,不再等到首次请求。

反模式

症状 为什么错 正确形态
改了实体/选项直接跑,行为还是旧的 冻结模型是 optimize 时点快照,不是活模型;指纹 + 实体形状双卡点会拦截漂移 重新 loom ef optimize(产物入库可 diff 评审)
loom.CompiledModel = true 启动抛"无 CompiledModel"/"指纹漂移"/"冻结模型过期" opt-in 了没 optimize;选项漂移;或改了实体未重跑 跑 optimize;选项走同源静态方法;改实体后必须重跑(编译期 KLSG242 会先提示)
EnsureCreated 建表成功但随后保存报 no such table :memory: 连串下每个连接是独立库 用打开的 SqliteConnection 对象传入,或用文件库
dotnet ef 报同上下文多个设计期工厂 自带工厂与生成工厂并存 自带工厂存在时生成器自动不发射;报歧义说明手写类与生成类同名,删一
多实例全开 AutoSeed 并发首启竞态 显式 db.SeedAsync() 控制时点(迁移后单点执行)
挂多实例还依赖单机雪花 workerId=0 双实例同 workerId 并号 = 碰撞风险 租约轮换形态(ResolveWorkerId 覆盖)或外部号源

想深入