Table of Contents

持久化主线

从“最小服务”到“可上线持久化”的决策链:上下文形态、UoW、键策略、建库方式、审计/租户、AOT 边界。 所有代码与 samples/MinimalService 同源; 消费者只使用 PackageReference(本地开发指向 pack feed,正式用 nuget.org 固定版本)。

1. 最小路径(单上下文)

builder.Services.AddLoomEf<AppDbContext>(o => o.UseSqlite("Data Source=min.db"));

// 上下文必须 partial —— 生成器发射 DbSet/模型配置;手写 DbSet 会 CS0102
public sealed partial class AppDbContext(DbContextOptions<AppDbContext> options)
    : LoomDbContext(options);

建库(demo 路径):

using (var scope = app.Services.CreateScope())
{
    scope.ServiceProvider.GetRequiredService<AppDbContext>().Database.EnsureCreated();
}

生产替换为迁移或入仓 DDL(见 §4)。EnsureCreated 不会随实体变化升级表结构。

2. 单上下文 vs UoW

场景 形态
一个上下文内的事务 直接注入 DbContext,SaveChangesAsync 即隐式事务
同库多上下文要原子 AddLoomUow(o => o.Engage<OrdersDb>().Engage<BillingDb>()) + BeginTransactionAsync
跨库/跨服务一致性 UoW 不提供假原子——走 outbox(消息面)

UoW 顺序:

builder.Services.AddLoomUow(o => o.Engage<AppDbContext>());

var uow = await sp.GetRequiredService<ILoomUowFactory>().CreateAsync();
await uow.BeginTransactionAsync(ct);
uow.Add(new Order { /* ... */ });
await uow.SaveChangesAsync(ct);   // 逐参与者保存(注册序)
await uow.CommitAsync(ct);        // 提交门结算 + UoW 钩子
  • 嵌套 CreateAsync = savepoint 边界(内层提交释放保存点,外层回滚仍全回滚);
  • 未显式提交就释放 = 回滚(治理立场);
  • 跨异构连接串 = 显式异常,指路 outbox。

3. 键策略

策略 声明 行为
Identity [EfEntity(..., Key = EfKeyStrategy.Identity)] 数据库自增;插入后回填
Snowflake Key = EfKeyStrategy.Snowflake 拦截器赋值;ValueGeneratedNever
Explicit Key = EfKeyStrategy.Explicit 调用方负责赋值

雪花键批量插入必须预赋键(否则多行键 0 进入 EF 身份映射冲突):

LoomSnowflakeIdGenerator.BatchAssign(orders, e => e.Id, (e, id) => e.Id = id);   // 仅补 Id == 0
db.Orders.AddRange(orders);
await db.SaveChangesAsync();

首选在创建处赋键:new Order { Id = LoomSnowflakeIdGenerator.Shared.NewId() }。

4. 建库:迁移 / DDL / 冻结模型

方式 适用 说明
EnsureCreated demo/测试 不升级表结构;AOT 下被 EF 上游拒绝
EF 迁移 SqlServer/Npgsql/MySQL 常规部署 迁移产物由消费方 CI 生成归档;运行期 Migrate 在 AOT 不可用
入仓 DDL 生产/AOT loom ef optimize 产物 + DDL 同批评审
迁移 bundle AOT 生产 设计期生成 bundle,由部署流程执行

CheckAndMigrateAsync 是运行期便利帮手(有迁移走迁移、无迁移 EnsureCreated), 已标 [RequiresDynamicCode]/[RequiresUnreferencedCode]——AOT 用 bundle/DDL。

5. 审计 / 租户 / ID 缝

builder.Services
    .AddSingleton<ILoomAuditIdentity>(myIdentity)   // Subject + TenantId
    .AddSingleton<ILoomIdGenerator, MySnowflake>(); // 雪花键缝
  • [EfEntity(..., EfEntityFeatures.FullAudited | Tenant | SoftDelete | AuditTrail)] 自动生成影子列与查询过滤器;
  • 审计身份缺失 = 记 system;租户实体无租户上下文 = 写入显式拒绝(不静默写空租户);
  • 租户过滤由生成物挂 ITenantAwareContext;跨租户运维走中枢面,不用 IgnoreQueryFilters。

6. AOT 边界

  • LoomAotMode=true + PublishAot=true;Mono AOT/WASM/IL2CPP 必须显式设置;
  • CompiledModel=true 需先 loom ef optimize,否则指纹/形状门 fail-fast;
  • 冻结模型覆盖模型/初始化面(注册、构建、指纹、DI、DDL);EF8 查询物化与 EF10 查询分别受 Expression.Compile / precompiled queries 上游边界(见 EF operations);
  • AddLoomEf 缺省反射序列化在 AOT 下 fail-fast;Outbox/JSON 用 JsonTypeInfo<T> 重载。

7. 失败面

症状 原因/处理
启动抛“冻结模型过期” 实体改了没重跑 loom ef optimize;按提示重跑
批量插入主键冲突 雪花键未预赋;用 BatchAssign
保存抛租户拒绝 写租户实体但无 TenantId;补 ILoomAuditIdentity
EnsureCreated 后保存 no such table :memory: 每个连接是独立库;传打开的连接或文件库
AOT 下 EnumStorage.String 报未注册 用 [EfEntity] 生成上下文(#211 自动注册);手写上下文显式 SetValueConverter