工作单元与消息面
跨上下文的本地原子边界(UoW);outbox 同事务落账 / inbox 幂等去重 / 历史清理; 与外部 MQ 的收发两端完整接口形态。 watch 可靠桥消费本页 outbox 运营面——见监听路由与消费完整性。
分布式一致性:Outbox 就是本地消息表
跨上下文、跨服务的一致性不走分布式事务(2PC)——本地消息表(事务性发件箱)模式: 集成事件与业务行在同一个本地事务里落账(同生共死:业务回滚 = 事件从未存在;业务提交 = 事件必然 可投递),再由事务外的派发循环把事件送到 MQ/远端,消费端以幂等收敛。这一模式里:
- 预留的本地消息表 =
loom.Outbox = true挂载的LoomOutboxMessage表(Type/Payload/TraceId/ Subject/Attempts/Dead 全运营字段)——不用建第二张表,也不用自写落账代码; - 写面 =
uow.Outbox.Enqueue(new OrderPlaced(orderId))——消息体 JSON 序列化承载,随 UoW 保存/提交与业务行同事务原子(不立即落库;提交后/无宿主 Enqueue = 显式异常); - 一致性边界 = UoW 同库原子(工作单元);跨库/跨服务 = outbox 派发 + 消费端幂等,最终一致。分布式事务语义(TCC/Saga 编排)是消费侧业务的领域, Loom 保证的是"事件不丢不重起步"。
工作单元(UoW——同库多上下文)
模块化单体下每模块一个上下文、同库共库是常态——跨上下文的本地原子边界就是 UoW:
// 组合根:参与者集声明序 = 保存序 = 提交序(泛型形态非参与者/漏挂能力根 = 编不过)
services.AddLoomUow(o =>
{
o.Engage<OrdersDbContext>();
o.Engage<BillingDbContext>(LoomUowEngagement.Factory); // Scoped/Factory/Pooled 三形态可混用
});
await using var uow = await uowFactory.CreateAsync(); // 参与者从当前 scope 解析
await uow.BeginTransactionAsync(); // owner 启事务,余者入列共享
uow.Add(new Order { ... }); // 按实体类型路由到所属上下文
uow.Outbox.Enqueue(new OrderPlaced(orderId)); // outbox 行同事务落账——与业务行同生共死
await uow.SaveChangesAsync(); // ① 逐参与者保存(脏判定跳过无变更者)
await uow.CommitAsync(); // ② owner 提交 → 提交门结算全体 → UoW 钩子
uow.OnCommit(async _ => await bus.PublishAsync(new OrderPlaced(orderId))); // 全体提交且结算后
要点:
- 边界:同库多上下文本地原子。异构连接 = 显式异常指路 outbox 编排(跨库是分布式一致性,不是 UoW 域)。
- 事务:owner(首参与者)启事务,其余参与者
UseTransaction入列——提交门/长事务监控经 owner 拦截器结算全体。 - Outbox:宿主上下文
LoomEfOptions.Outbox = true后表自动入模型;uow.Outbox.Enqueue与业务行同生共死,提交后/无事务 Enqueue = 显式异常。 - 钩子:参与者的
db.OnCommit是"该库提交后";uow.OnCommit是"全体提交且结算后"——跨上下文编排(两库都成功才发集成事件)用 UoW 级。 - 嵌套:内层
CreateAsync自动识别(全部参与者被活外层拥有 = savepoint 边界)——内层提交 = 释放保存点(外层回滚仍全回滚);内层回滚 = 部分丢弃(内层边界随即终结,参与者不再用于跟踪操作);内层活跃期间外层写操作 = 显式挂起异常。 - 手动保存点:长事务内自划可回退区间——
uow.CreateSavepointAsync()(缺省自动命名)→ 局部失败uow.RollbackToSavepointAsync(name)→ 事务边界继续(可再写/再打点/再提交,与嵌套回退即终结的关键差异);ReleaseSavepointAsyncLIFO 须栈顶;嵌套 UoW 与挂起态下禁用;loom_ef_uow_savepoint_create/rollback/release_total三计数器。 - 观测:
loom_ef_uow_commit_total/loom_ef_uow_rollback_total计数 +loom_ef_uow_participants直方图;钩子载荷带 Subject/TraceId/Duration;UoW 钩子异常进loom_ef_uow_hook_fail_total(警告日志,提交/回滚结果不变)。
AOT:Outbox.Enqueue 缺省反射 STS 在 NativeAOT 下 fail-fast——改用 Enqueue(message, JsonTypeInfo<T>)
(源生成 JsonSerializerContext 的 Default.Xxx)或传 serializePayload;owned JSON 列的
LoomJsonPath.RowToJson<T>(value, JsonTypeInfo<T>) 为 AOT 安全桥(非泛型 RowToJson(object) 标 RUC/RDC)。
消息面:Outbox 派发 / Inbox 去重 / 历史清理
// EF 缝一行:表挂载 + 存储自动注册(一宿主原则——第二个上下文再 opt-in = 显式异常)
services.AddLoomEf<Billing>(o => o.UseSqlite(cs), loom =>
{
loom.Outbox = true; // outbox 表入模型 + ILoomOutboxStore 自动注册
loom.Inbox = true; // inbox 去重表入模型 + ILoomInbox 自动注册
});
// services 缝:进程级生命周期与投递策略(与存储 opt-in 部署正交——API 进程可不挂循环)
services.AddSingleton<ILoomOutboxDelivery, HttpDelivery>(); // 投递策略(消费层供,Loom 传输无关)
services.AddLoomOutboxDispatcher(o => o.PollInterval = TimeSpan.FromSeconds(1)); // 派发循环
services.AddLoomOutboxCleanup(o => o.DispatchedRetention = TimeSpan.FromDays(7)); // 历史清扫
写面(同事务落账)与读面(派发去重清理):
await using var uow = await uowFactory.CreateAsync(); // 或直用上下文 SaveChanges
uow.Outbox.Enqueue(new OrderPlaced(orderId)); // outbox 行与业务行同生共死(恰一次落账)
// 消费端:TryBegin 原子占位 → 处理 → Done;失败 Abandon 释放占位(下次投递可重处理)
if (await inbox.TryBeginAsync("billing", messageId))
{
try { Handle(message); await inbox.DoneAsync("billing", messageId); }
catch { await inbox.AbandonAsync("billing", messageId); throw; }
} // false = 重复投递,幂等跳过
要点:
- 两段旅程:落账在事务内(EF 提交门,恰一次);投递/重试/清理在事务外(至少一次 + 消费端 inbox 幂等收敛)。
- 永久失败信号:投递实现抛
LoomOutboxPermanentDeliveryException(业务 4xx 类拒绝)= 立即死信;技术失败走指数退避,超限死信。两勿混。 - 部署正交:派发/清理循环是宿主 BackgroundService——API 进程只写、独立 Worker 只读+派发时,两进程都
Outbox = true,只有 Worker 挂AddLoomOutboxDispatcher()。 - 绑定注意:store/inbox 的上下文租借由 AddLoomEf 自动选型(Scoped 补工厂)——不要手写
AddSingleton<ILoomOutboxStore>(根容器解析 scoped = 捕获依赖,并发派发必炸)。 - 观测:
loom_ef_outbox_pending/loom_ef_outbox_dead/loom_ef_outbox_requeue_total/loom_ef_inbox_incomplete/loom_ef_inbox_stuck_reclaim_total。
外部 MQ 收发两端:接口形态完整示例
Loom 传输无关——MQ 客户端、拓扑、序列化目标格式全部归你的 ILoomOutboxDelivery 实现。
两端接口各只有一个:
发布端:实现 ILoomOutboxDelivery(把 outbox 行送到 MQ)
派发循环从本地消息表取出行(LoomOutboxMessage:MessageId/Type/Payload/TraceId/Subject/Attempts),
逐条调你的实现;抛普通异常 = 技术失败走退避重试,抛 LoomOutboxPermanentDeliveryException = 立即死信:
public sealed class RabbitMqDelivery(IChannelPool channels) : ILoomOutboxDelivery
{
// 自管超时(建议 30s 级——目标端点卡死不拖垮派发循环)
public async ValueTask DeliverAsync(LoomOutboxMessage message, CancellationToken ct = default)
{
var channel = await channels.RentAsync(ct);
var props = new Publication { MessageId = message.MessageId.ToString(), Type = message.Type };
// Type 路由到交换机(loom.watch 桥消息与业务消息可按 Type 分拓扑)
var routingKey = message.Type switch
{
"loom.watch" => "loom.events",
_ => $"orders.{message.Type}",
};
await channel.BasicPublishAsync("orders-ex", routingKey,
body: JsonSerializer.SerializeToUtf8Bytes(new
{
message.MessageId, message.Type, message.Payload,
message.TraceId, message.Subject, message.OccurredAtUtc,
}), ct);
}
}
// 装配(见上文「消息面」):AddSingleton<ILoomOutboxDelivery, RabbitMqDelivery>() + AddLoomOutboxDispatcher()
消费端:订阅 MQ + ILoomInbox 幂等三步
从 MQ 订阅到事件后,幂等由 inbox 三步收口——TryBeginAsync 原子占位(重复投递返回 false),
成功 DoneAsync,失败 AbandonAsync 释放占位让下次投递重处理:
public sealed class OrderPlacedConsumer(IServiceProvider sp, ILoomInbox inbox)
{
public async Task OnMessageAsync(Guid messageId, string payloadJson, CancellationToken ct)
{
// 幂等门:false = 重复投递,直接 ack 跳过
if (!await inbox.TryBeginAsync("orders-worker", messageId, ct)) return;
try
{
var evt = JsonSerializer.Deserialize<OrderPlaced>(payloadJson)!;
await using var scope = sp.CreateAsyncScope();
var db = scope.ServiceProvider.GetRequiredService<BillingDbContext>();
db.CreditAccounts.Add(new Credit(evt.AccountId, evt.Amount));
await db.SaveChangesAsync(ct);
await inbox.DoneAsync("orders-worker", messageId, ct); // 处理完成
}
catch
{
await inbox.AbandonAsync("orders-worker", messageId, ct); // 释放占位——下次投递重处理
throw; // MQ 侧行 nack/重投由消费骨架定
}
}
}
消费端宿主同样 loom.Inbox = true 挂载去重表(可与 outbox 同库分宿主,见一宿主原则);
consumer 名区分同一张表内的多个消费者。挂死自愈与清理:ReclaimStuckAsync(占位超时回收)、
PurgeCompletedAsync(已完成清理)——框架运维面已内置。
反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
| 跨库多上下文塞进同一个 UoW | Create 抛"连接串不同"——UoW 内部复用 owner 连接(同连接串即可,无需手工传同一实例);异构库共享不了本地事务 | 各自独立事务 + outbox 编排一致性(跨库是分布式一致性域) |
| 内层活跃期间写外层 UoW | 抛"外层挂起"——外层交错写会被 savepoint 事务级回滚误伤成假账 | 内层提交/回滚/释放后再动外层 |
UoW 内参与者自己 BeginTransaction |
事务归 UoW 拥有,自带事务 = 显式异常 | 用 UoW 共享事务(嵌套边界用嵌套 UoW 的 savepoint) |
手写 AddSingleton<ILoomOutboxStore>(sp => new ...(sp.GetRequiredService<TContext>())) |
根容器解析 scoped 上下文 = 捕获依赖——上下文永不释放 + 非线程安全并发派发必炸 | loom.Outbox = true 开关自动注册(租借形态自动选型) |
两个上下文都 Outbox = true |
outbox 表只挂一个宿主——注册即抛"一宿主原则"冲突 | 收敛到唯一宿主(撤另一处开关) |
TryBegin 后处理失败既不 Done 也不 Abandon |
占位行残留 = 后续投递全部幂等跳过,消息卡死 | catch 里 AbandonAsync 释放占位 |
| outbox 表只写不清 | 死数据无限涨 | AddLoomOutboxCleanup()(保留期可配,独立 Worker/Job 可挂) |
| 投递实现把业务拒绝和网络失败同处理 | 4xx 重发无意义白烧退避 | 业务永久拒绝抛 LoomOutboxPermanentDeliveryException(立即死信) |
| 消费端不做幂等直接处理 | outbox 投递是至少一次——MQ 重投/多实例竞争下必然重复 | ILoomInbox 三步收口(TryBegin/Done/Abandon) |
在 ILoomOutboxDelivery 里写业务逻辑 |
delivery 是投递适配器(送到 MQ 即返回)——业务在消费端 | 派发循环/退避/死信归 Loom,MQ 拓扑与消费动作归两端实现 |
| 消费失败既不 Done 也不 Abandon 还吞异常 | 占位残留 = 后续投递全部幂等跳过,消息卡死且无感知 | catch 里 AbandonAsync 并把异常交给 MQ 骨架 |
| 跨服务一致性期待 2PC | 分布式事务不是 outbox 域——outbox 给的是"事件不丢不重起步"的最终一致 | 本地消息表 + 消费端幂等;跨库编排见 UoW 边界 |
| 多进程都挂派发循环抢扫同一张表 | 不坏但浪费 + 日志噪音 | 独立开关——只在 Worker 进程 AddLoomOutboxDispatcher() |
想深入
- watch 可靠桥复用本页运营面:监听路由与消费完整性
- 审计缺省进 outbox:审计与操作日志
- 缝接口:
ILoomOutboxStore/ILoomOutboxDelivery/ILoomInbox——SPI 扩展点