using Dpz.Core.MessageQueue.Abstractions;
using Dpz.Core.MessageQueue.Models;
using Dpz.Core.MessageQueue.RabbitMQ;
using Microsoft.Extensions.DependencyInjection;

namespace Dpz.Core.Service;

public static class MessageOutboxExtensions
{
    /// <summary>
    /// 启用 Outbox 模式。需在 AddRabbitMQ() 之后调用。
    /// 会将 IMessagePublisher&lt;T&gt; 替换为带 Outbox 追踪的装饰器实现,
    /// 并以 Singleton 适配器(<see cref="ScopedOutboxStoreAdapter"/>)注册 IMessageOutboxStore,
    /// 内部每次操作通过 IServiceScopeFactory 创建独立 Scope 解析 Scoped 的 IMongoMessageOutboxStore。
    /// </summary>
    public static IServiceCollection AddMessageOutbox(this IServiceCollection services)
    {
        // 将具体类型 RabbitMQPublisher<T> 单独注册一次,
        // 供 OutboxMessagePublisher<T> 通过具体类型注入(绕过装饰器死循环)
        services.AddSingleton(typeof(RabbitMQPublisher<>));

        // 覆盖 IMessagePublisher<T>(最后注册者胜出)
        services.AddSingleton(typeof(IMessagePublisher<>), typeof(OutboxMessagePublisher<>));

        // 覆盖 null 实现,启用真实的 RabbitMQ 重发
        services.AddSingleton<IMessageOutboxRetryPublisher, RabbitMQRawPublisher>();

        // IMessageOutboxStore 以 Singleton 适配器注册,内部每次调用通过 IServiceScopeFactory
        // 创建独立 Scope 来解析 Scoped 的 IMongoMessageOutboxStore,避免 captive dependency
        services.AddSingleton<IMessageOutboxStore>(sp => new ScopedOutboxStoreAdapter(
            sp.GetRequiredService<IServiceScopeFactory>()
        ));

        return services;
    }

    /// <summary>
    /// Singleton 适配器:将 IMessageOutboxStore 的每次调用委托给新创建的 Scope 中的
    /// IMongoMessageOutboxStore(Scoped),解决 Singleton 持有 Scoped 依赖的问题。
    /// </summary>
    private sealed class ScopedOutboxStoreAdapter(IServiceScopeFactory scopeFactory)
        : IMessageOutboxStore
    {
        public async Task CreateAsync(
            string messageId,
            string messageType,
            string exchange,
            string routingKey,
            string payload,
            string? source,
            CancellationToken cancellationToken = default
        )
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            await scope
                .ServiceProvider.GetRequiredService<IMongoMessageOutboxStore>()
                .CreateAsync(
                    messageId,
                    messageType,
                    exchange,
                    routingKey,
                    payload,
                    source,
                    cancellationToken
                );
        }

        public async Task MarkSentAsync(
            string messageId,
            CancellationToken cancellationToken = default
        )
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            await scope
                .ServiceProvider.GetRequiredService<IMongoMessageOutboxStore>()
                .MarkSentAsync(messageId, cancellationToken);
        }

        public async Task MarkPublishFailedAsync(
            string messageId,
            string error,
            CancellationToken cancellationToken = default
        )
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            await scope
                .ServiceProvider.GetRequiredService<IMongoMessageOutboxStore>()
                .MarkPublishFailedAsync(messageId, error, cancellationToken);
        }

        public async Task MarkConsumedAsync(
            string messageId,
            CancellationToken cancellationToken = default
        )
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            await scope
                .ServiceProvider.GetRequiredService<IMongoMessageOutboxStore>()
                .MarkConsumedAsync(messageId, cancellationToken);
        }

        public async Task RecordConsumeAttemptFailedAsync(
            string messageId,
            string error,
            CancellationToken cancellationToken = default
        )
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            await scope
                .ServiceProvider.GetRequiredService<IMongoMessageOutboxStore>()
                .RecordConsumeAttemptFailedAsync(messageId, error, cancellationToken);
        }

        public async Task MarkConsumeFailedAsync(
            string messageId,
            string error,
            CancellationToken cancellationToken = default
        )
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            await scope
                .ServiceProvider.GetRequiredService<IMongoMessageOutboxStore>()
                .MarkConsumeFailedAsync(messageId, error, cancellationToken);
        }

        public async Task<IReadOnlyList<MessageOutboxEntry>> GetPendingPublishRetryAsync(
            int batchSize,
            CancellationToken cancellationToken = default
        )
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            return await scope
                .ServiceProvider.GetRequiredService<IMongoMessageOutboxStore>()
                .GetPendingPublishRetryAsync(batchSize, cancellationToken);
        }

        public async Task<IReadOnlyList<MessageOutboxEntry>> GetPendingConsumeRetryAsync(
            int batchSize,
            CancellationToken cancellationToken = default
        )
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            return await scope
                .ServiceProvider.GetRequiredService<IMongoMessageOutboxStore>()
                .GetPendingConsumeRetryAsync(batchSize, cancellationToken);
        }

        public async Task<IReadOnlyList<MessageOutboxEntry>> GetUnconsumedSentAsync(
            DateTime sentBefore,
            int batchSize,
            CancellationToken cancellationToken = default
        )
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            return await scope
                .ServiceProvider.GetRequiredService<IMongoMessageOutboxStore>()
                .GetUnconsumedSentAsync(sentBefore, batchSize, cancellationToken);
        }

        public async Task MarkConsumeRedeliveredAsync(
            string messageId,
            string reason,
            CancellationToken cancellationToken = default
        )
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            await scope
                .ServiceProvider.GetRequiredService<IMongoMessageOutboxStore>()
                .MarkConsumeRedeliveredAsync(messageId, reason, cancellationToken);
        }
    }
}
⚠⚠    以下内容为AI分析的结果,请根据实际情况进行判断。

一句话定位

MessageOutboxExtensions.cs 是 Outbox 模式在业务层的注册入口:把 AddRabbitMQ 给出的“裸发布器 + 空实现”整体替换为“带 Outbox 追踪的装饰发布器 + MongoDB 存储 + 真实重发器”,并用一个单例适配器桥接 Scoped 的 Mongo 存储。

关键类型与方法

AddMessageOutbox(this IServiceCollection) —— 一次调用完成四处覆盖,全部依赖 DI「最后注册者胜出」:

  1. AddSingleton(typeof(RabbitMQPublisher<>)):把具体泛型类型再注册一遍。因为下一行把 IMessagePublisher<T> 换成了 OutboxMessagePublisher<T>,而后者构造函数要的是具体类型 RabbitMQPublisher<TMessage>(见 OutboxMessagePublisher.cs)。若用接口注入会形成装饰器自我递归。这是整个方法的隐藏前提。
  2. IMessagePublisher<> → OutboxMessagePublisher<>:覆盖 MessageQueueServiceExtensions.cs 里的 RabbitMQPublisher<>。
  3. IMessageOutboxRetryPublisher → RabbitMQRawPublisher:覆盖 NullMessageOutboxRetryPublisher,让 MessageOutboxRetryService 的重发真正打到 Broker(mandatory: true + 发布确认,路由失败会抛异常而不是假装成功)。
  4. IMessageOutboxStore → 工厂 lambda 产出 ScopedOutboxStoreAdapter。

ScopedOutboxStoreAdapter(private sealed 嵌套类) —— 实现 IMessageOutboxStore 的全部 12 个方法,每个方法体都是同一套模板:CreateAsyncScope() → GetRequiredService<IMongoMessageOutboxStore>() → 转发一次 → 释放 scope。它本身不持有任何状态,也不缓存 store 实例,因此不存在 captive dependency。注意它是 private 的,容器只能通过工厂创建,无法按类型解析,也就无法被外部替换或单测直接实例化。

依赖与协作

  • 依赖上层抽象:IMessageOutboxStore、IMessageOutboxRetryPublisher、MessageOutboxEntry(跨 scope 返回的是轻量 DTO,不是数据库实体,所以 scope 释放后数据仍可用)。
  • 依赖 IMongoMessageOutboxStore 的生命周期约定:它位于 Dpz.Core.Service.RepositoryService 命名空间,由源生成器扫描后默认按 Scoped 注册,其实现 MongoMessageOutboxStore 依赖 Scoped 的 IRepository<>、IMapper。由于该类带 [InvalidateCache],生成器实际注册的是“具体类型 Scoped + IMongoMessageOutboxStore → 生成的缓存装饰器(Scoped)”,适配器解析到的是装饰器版本,这也意味着每次 CreateAsync 都会触发一次缓存失效逻辑。
  • 调用方:唯一注册点是 AddBusinessServices 中的 services.AddRabbitMQ(configuration).AddMessageOutbox()(ServiceExtensions.cs),因此 Web、WebApi、Web.Jobs 三个宿主全部自动启用,顺序“先 AddRabbitMQ 后 AddMessageOutbox”在这里是硬编码保证的。
  • 消费端:RabbitMQConsumerBackgroundServiceBase 与 MessageOutboxRetryService 都是以 Singleton 身份直接注入 IMessageOutboxStore,拿到的就是这个适配器——这正是它必须存在的原因(否则 Singleton 直接依赖 Scoped 会被 DI 校验或作用域泄漏打挂)。

流程/时序

单条消息发布(生产者路径):

sequenceDiagram
    participant B as 业务代码
    participant P as OutboxMessagePublisher
    participant A as ScopedOutboxStoreAdapter
    participant S1 as Scope1 / MongoStore
    participant R as RabbitMQPublisher
    participant S2 as Scope2 / MongoStore
    B->>P: PublishAsync(message)
    P->>A: CreateAsync(...)
    A->>S1: 新建 scope 并写入 Pending
    A-->>P: scope 释放
    P->>R: PublishAsync(message)
    alt 发布成功
        P->>A: MarkSentAsync
        A->>S2: 新建 scope 标为 Sent
    else 抛异常
        P->>A: MarkPublishFailedAsync
        A->>S2: 新建 scope 记失败与退避
        P-->>B: 重新抛出
    end

关键点:一次逻辑操作被拆成两次独立的 scope 和两次独立的 Mongo 写入,Create 与 MarkSent 之间没有任何事务或会话保证。

需要注意的点

  • 调用顺序是隐式契约:注册顺序反过来(或在 AddMessageOutbox 之后再调 AddRabbitMQ)会让 IMessagePublisher<T> 被裸发布器覆盖,Outbox 静默失效,没有任何日志或异常提示。
  • 不加去重:重复调用 AddMessageOutbox 会累积重复描述符(几个 Singleton 覆盖项无害,但 RabbitMQPublisher<> 会多一条)。当前靠 AddBusinessServices 只调一次来保证。
  • 两次 scope 带来的一致性缺口:MarkSentAsync 失败(Mongo 抖动)会被 OutboxMessagePublisher 的 catch 捕获并标记为 PublishFailed 后重抛——而消息其实已经投递成功,随后补发 worker 会再发一次。也即语义是 at-least-once,消费端需要靠 MessageId 幂等。
  • 启动期不校验:若宿主没有先执行 AddDefaultServices()(即 AddGeneratedRepositoryServices()),IMongoMessageOutboxStore 不会被注册,适配器要到第一次发布/消费时才抛 InvalidOperationException,注册阶段完全看不出问题。
  • 每次调用都解析一遍完整链路:每个方法(包括消费确认 MarkConsumedAsync,每条消息一次)都会新建 scope、解析缓存装饰器 + Mongo 存储 + IRepository<>,都是轻微但不可忽略的固定开销;批处理场景(PublishBatchAsync 中逐条 Create、逐条 MarkSent)开销按消息数线性放大。
  • 未确认项:仓库中没有针对 ScopedOutboxStoreAdapter 的直接测试;集成测试 OutboxEndToEndIntegrationTests.cs 只验证「适配器等价行为」(每个操作独立 scope),实际适配器代码路径没有单测覆盖。
评论加载中...