工作单元(UoW)
同库多上下文共享事务的本地原子边界:声明参与者 → 创建 UoW → 路由操作 → 两段式提交。 上位:总览;消息与监听细节见工作单元与消息面;设计全文见仓内
docs/design/ef-uow-design.md。
何时用 UoW
一个业务动作要写多个 DbContext(模块化单体常态:订单库 + 账务库同实例),且要求要么全成功要么全回滚——这就是 UoW 的域。跨微服务/跨库实例 = 分布式一致性问题,走 Outbox 编排(UoW 明确不提供跨库假原子)。
声明参与者(编译期约束)
// 上下文实现 ILoomUowParticipant(能力根)——未实现者 Engage/AddLoomUow 编译期拒绝
public sealed partial class OrdersDbContext : LoomDbContext, ILoomUowParticipant
{
public OrdersDbContext(DbContextOptions<OrdersDbContext> options) : base(options) { }
}
services.AddLoomUow(o =>
{
o.Engage<OrdersDbContext>(); // Scoped(缺省——从当前 scope 解析)
o.Engage<BillingDbContext>(LoomUowEngagement.Factory); // Scoped / Factory / Pooled 三形态可混用
});
约束是泛型形参级别的(Engage<TContext> where TContext : LoomDbContext, ILoomUowParticipant)——没实现能力根的上下文根本编译不过,不存在运行期才发现的"忘声明"。
创建与两段式提交
await using var uow = await uowFactory.CreateAsync(); // 参与者从当前 scope 解析(或 CreateAsync(contexts[]) 显式传)
await uow.BeginTransactionAsync(); // owner(首参与者)启事务,其余参与者入列共享
uow.Add(new Order { ... }); // 按实体类型路由到所属上下文
await uow.SaveChangesAsync(); // ① 逐参与者保存(无变更者跳过)
await uow.CommitAsync(); // ② owner 提交 → 提交门结算全体 → UoW 钩子
- 路由面:
Add/AddRange/Update/UpdateRange/Remove/RemoveRange/Query<T>/Set<T>全按实体类型路由到所属上下文;实体同绑双上下文(n:n)= 创建时显式异常(拆分 UoW,不做歧义猜路由)。Context<TContext>()是最终逃生口。 - 连接归拢(#84):参与者只需连接串与 owner 相同——
CreateAsync内部把各参与者重指到 owner 的DbConnection(EF 复用同一连接,共享本地事务);无需手工传同一连接实例。连接串不同 = 异构库 (共享不了本地事务)→ 显式异常指路 outbox 编排。 - 未提交释放:
DisposeAsync未显式提交 = 回滚(治理立场)。 - 收编:
uow.Engage(context)在BeginTransactionAsync之前把晚发现的上下文扩进边界——收编后路由/保存照常;事务已启动后再 Engage = 显式异常(防 savepoint 事务级回滚误伤)。
嵌套(子事务语义)
外层 UoW 活跃时,factory.CreateAsync() 对全部参与者被外层拥有的组合自动识别为嵌套——内层边界即共享事务上的 savepoint:内层提交 = 释放保存点(部分持久,外层回滚仍全回滚);内层回滚 = 部分丢弃(内层边界随即终结,参与者不再用于跟踪操作——追踪态过期诚实边界);内层活跃期间外层写操作 = 显式挂起异常(防外层交错写被事务级回滚误伤成假账)。
手动保存点(长事务自划可回退区间)
不建子边界的轻量形态——在共享事务上打点、局部失败回退到点、事务边界继续:
await using var uow = await uowFactory.CreateAsync();
await uow.BeginTransactionAsync();
var sp = await uow.CreateSavepointAsync(); // 缺省自动命名(sp_{n}_{guid7})
// ... 一批写入 + SaveChangesAsync
await uow.RollbackToSavepointAsync(sp); // 局部失败:回退到点(其上全部作废 + 暂存截断)
// ★ 回退后事务边界继续——可再写、再打点、再提交(与嵌套回退即终结的关键差异)
uow.Add(new Order { ... });
await uow.SaveChangesAsync();
await uow.CommitAsync();
ReleaseSavepointAsync(name)主动释放(LIFO——须栈顶);回退到点 = 其上全部作废。- 嵌套 UoW 内不可再创建手动保存点(嵌套边界本身就是 savepoint 抽象);嵌套活跃期间外层同样禁用。
- provider 不支持时(MARS 启用的 SqlServer)
SupportsSavepoints= false,创建 = fail-fast 指路。
钩子与 Outbox
uow.OnCommit/OnRollback:全体参与者边界终结后依次执行(区别于参与者级db.OnCommit的"该库提交后")——跨上下文编排面。uow.Outbox.Enqueue(...):outbox 行与业务行同事务落账(须有 outbox 宿主——消息面)。
观测
| 计数器 | 语义 |
|---|---|
loom_ef_uow_commit_total / loom_ef_uow_rollback_total |
边界终结(提交/回滚) |
loom_ef_uow_participants |
参与者数直方图 |
loom_ef_uow_hook_fail_total |
UoW 级提交/回滚钩子异常(隔离计数——提交/回滚结果不变) |
loom_ef_uow_savepoint_create/rollback/release_total |
手动保存点三态 |
边界与反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
| 跨库上下文进同一 UoW | 异构连接 = 共享不了本地事务 | 跨库一致性走 outbox 编排 |
| 实体同绑双上下文还想共投 | n:n 路由歧义 = 假写风险 | 创建时显式异常;拆分 UoW 或收窄参与者 |
| 事务启动后才想加参与者 | savepoint 事务级回滚会误伤新上下文交错写 | 提前 Engage(Begin 之前) |
| 嵌套回退后继续用内层 | 追踪态与库不一致(EF savepoint 通病) | 内层回退即边界终结——外层继续 |
| 手动保存点在嵌套 UoW 里用 | 两层 savepoint 抽象叠加不可解释 | 用嵌套机制,或在外层打手动点 |