观测·种子·迁移·冻结模型
慢 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 覆盖)或外部号源 |
想深入
- 工具参数与指纹同源纪律:KernLab.Loom.Tools 包说明
- 配置键全表:配置参考