持久化主线
从“最小服务”到“可上线持久化”的决策链:上下文形态、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 |