使用 SQLite 和 Brighter 实现发件箱模式

简介  

本指南演示如何使用 SQLite 和 .NET 8，结合 Brighter 库 实现 **发件箱模式（Outbox Pattern）**，以确保数据库更新与消息发布之间的事务一致性。

项目目标  

处理 CreateNewOrder 命令，在事务成功时发布两个事件（OrderPlaced, OrderPaid）。如果发生错误（例如业务规则冲突），则回滚数据库更改和消息发布。

要求  

•  .NET 8+  
• 使用 Podman（或 Docker）运行本地容器：  
  • RabbitMQ
• [Brighter 与 RabbitMQ 的配置知识](https://dev.to/actor-dev/brighter-rabbitmq-como-configurar-brighter-com-rabbitmq-1lj5)  
• NuGet 包  
  • Paramore.Brighter.Extensions.DependencyInjection
  • Paramore.Brighter.Extensions.Hosting
  • Paramore.Brighter.MessagingGateway.RMQ
  • Paramore.Brighter.Outbox.Sqlite
  • Paramore.Brighter.ServiceActivator.Extensions.DependencyInjection
  • Paramore.Brighter.ServiceActivator.Extensions.Hosting

消息定义  

需要以下 3 条消息：CreateNewOrder, OrderPlaced, OrderPaid

public class CreateNewOrder() : Command(Guid.NewGuid())
{
    public decimal Value { get; set; }
}

public class OrderPlaced() : Event(Guid.NewGuid())
{
    public string OrderId { get; set; } = string.Empty;
    public decimal Value { get; set; }
}

public class OrderPaid() : Event(Guid.NewGuid())
{
    public string OrderId { get; set; } = string.Empty;
}

消息映射器  

仅发布 OrderPlaced 和 OrderPaid 到 RabbitMQ，需实现 JSON 序列化映射：

public class OrderPlacedMapper : IAmAMessageMapper
{
    public Message MapToMessage(OrderPlaced request)
    {
        var header = new MessageHeader();
        header.Id = request.Id;
        header.TimeStamp = DateTime.UtcNow;
        header.Topic = "order-placed";
        header.MessageType = MessageType.MT_EVENT;
        header.ReplyTo = ""; // 因 SQLite 实现的 bug
        var body = new MessageBody(JsonSerializer.Serialize(request));
        return new Message(header, body);
    }
    public OrderPlaced MapToRequest(Message message)
    {
        return JsonSerializer.Deserialize(message.Body.Bytes)!;
    }
}

public class OrderPaidMapper : IAmAMessageMapper
{
    public Message MapToMessage(OrderPaid request)
    {
        var header = new MessageHeader();
        header.Id = request.Id;
        header.TimeStamp = DateTime.UtcNow;
        header.Topic = "order-paid";
        header.MessageType = MessageType.MT_EVENT;
        header.ReplyTo = ""; // 因 SQLite 实现的 bug
        var body = new MessageBody(JsonSerializer.Serialize(request));
        return new Message(header, body);
    }
    public OrderPaid MapToRequest(Message message)
    {
        return JsonSerializer.Deserialize(message.Body.Bytes)!;
    }
}

注意：由于 SQLite 发件箱当前实现的 bug，需将 ReplyTo 设为空字符串（将在 V10 修复）。

请求处理器  

订单事件处理器  

对 OrderPlaced 和 OrderPaid 进行日志记录：

public class OrderPlaceHandler(ILogger logger) : RequestHandlerAsync
{
    public override Task HandleAsync(OrderPlaced command, CancellationToken cancellationToken = default)
    {
        logger.LogInformation("{OrderId} placed with value {OrderValue}", command.OrderId, command.Value);
        return base.HandleAsync(command, cancellationToken);
    }
}
public class OrderPaidHandler(ILogger logger) : RequestHandlerAsync
{
    public override Task HandleAsync(OrderPaid command, CancellationToken cancellationToken = default)
    {
        logger.LogInformation("{OrderId} paid", command.OrderId);
        return base.HandleAsync(command, cancellationToken);
    }
}

创建订单处理器  

处理 CreateNewOrder 命令，模拟业务流程并发布事件：

public class CreateNewOrderHandler(IAmACommandProcessor commandProcessor,
    IUnitOfWork unitOfWork,
    ILogger logger) : RequestHandlerAsync
{
    public override async Task HandleAsync(CreateNewOrder command, CancellationToken cancellationToken = default)
    {
        await unitOfWork.BeginTransactionAsync(cancellationToken);
        try
        {
            string id = Guid.NewGuid().ToString();
            logger.LogInformation("Creating a new order: {OrderId}", id);
            await Task.Delay(10, cancellationToken); // 模拟业务流程
            _ = await commandProcessor.DepositPostAsync(new OrderPlaced { OrderId = id, Value = command.Value }, cancellationToken: cancellationToken);
            if (command.Value % 3 == 0)
            {
                throw new InvalidOperationException("invalid value");
            }
            _ = await commandProcessor.DepositPostAsync(new OrderPaid { OrderId = id }, cancellationToken: cancellationToken);
            await unitOfWork.CommitAsync(cancellationToken);
            return await base.HandleAsync(command, cancellationToken);
        }
        catch
        {
            logger.LogError("Invalid data");
            await unitOfWork.RollbackAsync(cancellationToken);
            throw;
        }
    }
}

关键点：  
- DepositPostAsync 在同一事务中将消息存入发件箱。  
- 若抛出异常（如 InvalidOperationException），事务回滚，确保无孤立消息。

配置 SQLite  
1. 发件箱表结构  

CREATE TABLE IF NOT EXISTS "outbox_messages"(
  [MessageId] TEXT NOT NULL COLLATE NOCASE,
  [Topic] TEXT NULL,
  [MessageType] TEXT NULL,
  [Timestamp] TEXT NULL,
  [CorrelationId] TEXT NULL,
  [ReplyTo] TEXT NULL,
  [ContentType] TEXT NULL,  
  [Dispatched] TEXT NULL,
  [HeaderBag] TEXT NULL,
  [Body] TEXT NULL,
  CONSTRAINT[PK_MessageId] PRIMARY KEY([MessageId])
);

2. 依赖注入配置  

注册发件箱和事务：

services
    .AddServiceActivator(opt => { /* 订阅配置（参考前文） */ })
    .UseSqlOutbox(new SqliteConfiguration(ConnectionString, "outbox_messages"), typeof(SqliteConnectionProvider), ServiceLifetime.Scoped))      
    .UseSqliteTransactionConnectionProvider(typeof(SqliteConnectionProvider))
    .UseOutboxSweeper(opt => opt.BatchSize = 10);

原理：  
- UseSqliteOutbox 将发件箱绑定到 SQLite。  
- UseOutboxSweeper 配置后台轮询未发送消息。

3. 事务管理  

实现 ISqliteTransactionConnectionProvider 和 IUnitOfWork 以共享事务上下文：  

a. SqliteConnectionProvider  

public class SqliteConnectionProvider(SqliteUnitOfWork sqlConnection) : ISqliteTransactionConnectionProvider
{
    public SqliteConnection GetConnection() => sqlConnection.Connection;
    public Task GetConnectionAsync(CancellationToken cancellationToken = default) 
        => Task.FromResult(sqlConnection.Connection);
    public SqliteTransaction? GetTransaction() => sqlConnection.Transaction;
    public bool HasOpenTransaction => sqlConnection.Transaction != null;
    public bool IsSharedConnection => true;
}

b. UnitOfWork 接口  

public interface IUnitOfWork
{
    Task BeginTransactionAsync(CancellationToken cancellationToken, IsolationLevel isolationLevel = IsolationLevel.Serializable);
    Task CommitAsync(CancellationToken cancellationToken);
    Task RollbackAsync(CancellationToken cancellationToken);
}

c. SqliteUnitOfWork 实现  

public class SqliteUnitOfWork : IUnitOfWork
{
    public SqliteUnitOfWork(SqliteConfiguration configuration)
    {
        Connection = new(configuration.ConnectionString);
        Connection.Open();
    }
    public SqliteConnection Connection { get; }
    public SqliteTransaction? Transaction { get; private set; }

    public async Task BeginTransactionAsync(IsolationLevel isolationLevel = IsolationLevel.Serializable)
    {
        if (Transaction == null)
        {
            Transaction = (SqliteTransaction)await Connection.BeginTransactionAsync(isolationLevel);
        }
    }

    public async Task CommitAsync(CancellationToken cancellationToken)
    {
        if (Transaction != null)
        {
            await Transaction.CommitAsync(cancellationToken);
        }
    }

    public async Task RollbackAsync(CancellationToken cancellationToken)
    {
        if (Transaction != null)
        {
            await Transaction.RollbackAsync(cancellationToken);
        }
    }
}

d. 注册依赖注入  

services
    .AddScoped()
    .TryAddScoped(provider => provider.GetRequiredService());

结论  

通过 Brighter 和 SQLite 实现发件箱模式，确保了以下特性：  
1. 事务一致性

• 仅当事务提交成功时才发布消息（通过 DepositPostAsync）。  
• 若处理器失败（如模拟错误），事务回滚，消息不会孤立发送。  

2. 容错能力（Outbox Sweeper)
   - UseOutboxSweeper 轮询未发送消息并重试，直到 RabbitMQ 确认。  
3. 解耦架构 
   - 应用专注本地事务，Brighter 异步处理消息发布，简化扩展性。

参考  

包含完整代码的 Github

using System.Data;
using System.Text.Json;
using Microsoft.Data.Sqlite;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Paramore.Brighter;
using Paramore.Brighter.Extensions.DependencyInjection;
using Paramore.Brighter.Extensions.Hosting;
using Paramore.Brighter.MessagingGateway.RMQ;
using Paramore.Brighter.Outbox.Sqlite;
using Paramore.Brighter.ServiceActivator.Extensions.DependencyInjection;
using Paramore.Brighter.ServiceActivator.Extensions.Hosting;
using Paramore.Brighter.Sqlite;
using Serilog;

const string ConnectionString = "Data Source=brighter.db";

await using (SqliteConnection connection = new(ConnectionString))
{
    await connection.OpenAsync();

    await using var command = connection.CreateCommand();
    command.CommandText =
      """
      CREATE TABLE IF NOT EXISTS "outbox_messages"(
        [MessageId] TEXT NOT NULL COLLATE NOCASE,
        [Topic] TEXT NULL,
        [MessageType] TEXT NULL,
        [Timestamp] TEXT NULL,
        [CorrelationId] TEXT NULL,
        [ReplyTo] TEXT NULL,
        [ContentType] TEXT NULL,  
        [Dispatched] TEXT NULL,
        [HeaderBag] TEXT NULL,
        [Body] TEXT NULL,
        CONSTRAINT[PK_MessageId] PRIMARY KEY([MessageId])
      );
      """;
    // MessageId, MessageType, Topic, Timestamp, CorrelationId, ReplyTo, ContentType, HeaderBag, Body
    _ = await command.ExecuteNonQueryAsync();

}

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .MinimumLevel.Override("Paramore.Brighter", Serilog.Events.LogEventLevel.Warning)
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .CreateLogger();

IHost host = new HostBuilder()
    .UseSerilog()
    .ConfigureServices(
        (ctx, services) =>
        {
            RmqMessagingGatewayConnection connection = new()
            {
                AmpqUri = new AmqpUriSpecification(new Uri("amqp://guest:guest@localhost:5672")),

                Exchange = new Exchange("paramore.brighter.exchange"),
            };

            services
              .AddScoped()
              .TryAddScoped(provider => provider.GetRequiredService());

            _ = services
                .AddHostedService()
                .AddServiceActivator(opt =>
                {
                    opt.Subscriptions =
                    [
                        new RmqSubscription(
                            new SubscriptionName("subscription"),
                            new ChannelName("queue-order-placed"),
                            new RoutingKey("order-placed"),
                            makeChannels: OnMissingChannel.Create,
                            runAsync: true
                        ),

                        new RmqSubscription(
                            new SubscriptionName("subscription"),
                            new ChannelName("queue-order-paid"),
                            new RoutingKey("order-paid"),
                            makeChannels: OnMissingChannel.Create,
                            runAsync: true
                        ),
                    ];

                    opt.ChannelFactory = new ChannelFactory(
                        new RmqMessageConsumerFactory(connection)
                    );
                })
                .AutoFromAssemblies()
                .UseSqliteOutbox(new SqliteConfiguration(ConnectionString, "outbox_messages"), typeof(SqliteConnectionProvider), ServiceLifetime.Scoped)
                .UseSqliteTransactionConnectionProvider(typeof(SqliteConnectionProvider))
                .UseOutboxSweeper(opt =>
                {
                    opt.BatchSize = 10;
                })
                .UseExternalBus(
                    new RmqProducerRegistryFactory(
                        connection,
                        [
                            new RmqPublication
                            {
                                MakeChannels = OnMissingChannel.Create,
                                Topic = new RoutingKey("order-paid"),
                            },
                            new RmqPublication
                            {
                                MakeChannels = OnMissingChannel.Create,
                                Topic = new RoutingKey("order-placed"),
                            },
                        ]
                    ).Create()
                );

        }
    )
    .Build();


await host.StartAsync();

CancellationTokenSource cancellationTokenSource = new();

Console.CancelKeyPress += (_, _) => cancellationTokenSource.Cancel();

while (!cancellationTokenSource.IsCancellationRequested)
{
    await Task.Delay(TimeSpan.FromSeconds(10));
    Console.Write("Type an order value (or q to quit): ");
    string? tmp = Console.ReadLine();

    if (string.IsNullOrEmpty(tmp))
    {
        continue;
    }

    if (tmp == "q")
    {
        break;
    }

    if (!decimal.TryParse(tmp, out decimal value))
    {
        continue;
    }

    try
    {
        using var scope = host.Services.CreateScope();
        var process = scope.ServiceProvider.GetRequiredService();
        await process.SendAsync(new CreateNewOrder { Value = value });
    }
    catch
    {
        // ignore any error
    }
}

await host.StopAsync();

public class CreateNewOrder() : Command(Guid.NewGuid())
{
    public decimal Value { get; set; }
}

public class OrderPlaced() : Event(Guid.NewGuid())
{
    public string OrderId { get; set; } = string.Empty;
    public decimal Value { get; set; }
}


public class OrderPaid() : Event(Guid.NewGuid())
{
    public string OrderId { get; set; } = string.Empty;
}

public class CreateNewOrderHandler(IAmACommandProcessor commandProcessor,
    IUnitOfWork unitOfWork,
    ILogger logger) : RequestHandlerAsync
{
    public override async Task HandleAsync(CreateNewOrder command, CancellationToken cancellationToken = default)
    {
        await unitOfWork.BeginTransactionAsync();
        try
        {
            var id = Guid.NewGuid().ToString();
            logger.LogInformation("Creating a new order: {OrderId}", id);

            await Task.Delay(10, cancellationToken); // emulating an process

            _ = await commandProcessor.DepositPostAsync(new OrderPlaced { OrderId = id, Value = command.Value }, cancellationToken: cancellationToken);
            if (command.Value % 3 == 0)
            {
                throw new InvalidOperationException("invalid value");
            }

            _ = await commandProcessor.DepositPostAsync(new OrderPaid { OrderId = id }, cancellationToken: cancellationToken);

            await unitOfWork.CommitAsync(cancellationToken);
            return await base.HandleAsync(command, cancellationToken);
        }
        catch
        {
            logger.LogError("Invalid data");
            await unitOfWork.RollbackAsync(cancellationToken);
            throw;
        }
    }
}

public class OrderPlaceHandler(ILogger logger) : RequestHandlerAsync
{
    public override Task HandleAsync(OrderPlaced command, CancellationToken cancellationToken = default)
    {
        logger.LogInformation("{OrderId} placed with value {OrderValue}", command.OrderId, command.Value);
        return base.HandleAsync(command, cancellationToken);
    }
}

public class OrderPaidHandler(ILogger logger) : RequestHandlerAsync
{
    public override Task HandleAsync(OrderPaid command, CancellationToken cancellationToken = default)
    {
        logger.LogInformation("{OrderId} paid", command.OrderId);
        return base.HandleAsync(command, cancellationToken);
    }
}

public class OrderPlacedMapper : IAmAMessageMapper
{
    public Message MapToMessage(OrderPlaced request)
    {
        var header = new MessageHeader();
        header.Id = request.Id;
        header.TimeStamp = DateTime.UtcNow;
        header.Topic = "order-placed";
        header.MessageType = MessageType.MT_EVENT;
        header.ReplyTo = "";

        var body = new MessageBody(JsonSerializer.Serialize(request));
        return new Message(header, body);
    }

    public OrderPlaced MapToRequest(Message message)
    {
        return JsonSerializer.Deserialize(message.Body.Bytes)!;
    }
}

public class OrderPaidMapper : IAmAMessageMapper
{
    public Message MapToMessage(OrderPaid request)
    {
        var header = new MessageHeader();
        header.Id = request.Id;
        header.TimeStamp = DateTime.UtcNow;
        header.Topic = "order-paid";
        header.MessageType = MessageType.MT_EVENT;
        header.ReplyTo = "";

        var body = new MessageBody(JsonSerializer.Serialize(request));
        return new Message(header, body);
    }

    public OrderPaid MapToRequest(Message message)
    {
        return JsonSerializer.Deserialize(message.Body.Bytes)!;
    }
}

public class SqliteConnectionProvider(SqliteUnitOfWork sqlConnection) : ISqliteTransactionConnectionProvider
{
    public SqliteConnection GetConnection()
    {
        return sqlConnection.Connection;
    }

    public Task GetConnectionAsync(CancellationToken cancellationToken = default)
    {
        return Task.FromResult(sqlConnection.Connection);
    }

    public SqliteTransaction? GetTransaction()
    {
        return sqlConnection.Transaction;
    }

    public bool HasOpenTransaction => sqlConnection.Transaction != null;
    public bool IsSharedConnection => true;
}

public interface IUnitOfWork
{
    Task BeginTransactionAsync(IsolationLevel isolationLevel = IsolationLevel.Serializable);
    Task CommitAsync(CancellationToken cancellationToken);
    Task RollbackAsync(CancellationToken cancellationToken);
}

public class SqliteUnitOfWork : IUnitOfWork
{
    public SqliteUnitOfWork(SqliteConfiguration configuration)
    {
        Connection = new(configuration.ConnectionString);
        Connection.Open();
    }

    public SqliteConnection Connection { get; }
    public SqliteTransaction? Transaction { get; private set; }

    public async Task BeginTransactionAsync(IsolationLevel isolationLevel = IsolationLevel.Serializable)
    {
        if (Transaction == null)
        {
            Transaction = (SqliteTransaction)await Connection.BeginTransactionAsync(isolationLevel);
        }
    }

    public async Task CommitAsync(CancellationToken cancellationToken)
    {
        if (Transaction != null)
        {
            await Transaction.CommitAsync(cancellationToken);
        }
    }

    public async Task RollbackAsync(CancellationToken cancellationToken)
    {
        if (Transaction != null)
        {
            await Transaction.RollbackAsync(cancellationToken);
        }
    }
}