CAP 分布式事务的消息持久化与存储选型完全指南

原创2026-10-08 21:24:051,835 阅读
文章标签:后端消息队列微服务

CAP 分布式事务的消息持久化与存储选型完全指南

本篇技术指南聚焦 .NET 微服务分布式事务框架 CAP 的消息持久化与存储层:为什么 CAP 必须依赖持久化存储、发送前/发送后两阶段的可靠性保障机制如何运作、官方支持的存储提供程序如何配置与选型、以及消息在数据库中的字段结构与生命周期管理。读完本文,你将掌握 CAP 存储层的完整架构原理,并能够针对 SQL Server、MySQL、PostgreSQL、MongoDB 与 In-Memory Storage 做出正确的选型与配置。

为什么消息必须"落地":可靠性是分布式事务的基石

CAP 定位为基于最终一致性(Outbox 模式)的微服务分布式事务解决方案,其核心前提是任何情况下消息都不能丢失。正如 存储通用文档 所指出的:CAP 需要使用具有持久化功能的存储介质(数据库或其他 NoSQL 设施)来保存事件消息,以应对一切环境或网络异常导致的丢失。消息的可靠性是分布式事务的基石,一旦消息在落库前或投递中丢失,整个最终一致性链路就会断裂,业务数据与事件将无法对齐。

在实现层面,这一"不丢失"的承诺通过两个阶段来完成:发送前的本地事务落库 与 发送后的消息队列持久化。

发送前:与业务代码共用同一数据库事务(强一致落库)

在消息进入消息队列(Broker)之前,CAP 使用本地数据库表对消息进行持久化。此时即便消息队列出现异常或网络错误,消息也已经在数据库中,不会丢失。

这一机制可靠性的关键设计在于:CAP 使用与业务代码相同的数据库事务来保证业务操作与 CAP 消息持久化的强一致性。也就是说,业务数据写入与 CAP 消息表插入发生在同一个本地事务中,任何一方发生异常,数据库都会整体回滚。这正是 Outbox 模式的经典做法——先保证"业务变更"与"事件记录"原子提交,再由后台进程把事件可靠地转发到消息队列。

从源码可以印证这一设计:IDataStorage.cs 中的 StoreMessageAsync 方法签名携带 object? transaction = null 参数,各存储提供程序将该参数转换为底层数据库事务对象(如 IDbTransaction 或 EF Core 的 IDbContextTransaction),从而实现消息写入与业务操作的同事务提交。例如 SQL Server、MySQL、PostgreSQL 的 IDbContextTransaction.CAP.cs 等扩展就是为这一目的而提供的。

事务发布的两种写法(ADO.NET 与 EF Core)

无论使用哪种关系型存储,事务发布消息的写法都是统一的。ADO.NET 方式使用连接对象上的 BeginTransaction(_capBus, autoCommit: false) 扩展方法:

private readonly ICapPublisher _capBus;

using (var connection = new SqlConnection("ConnectionString"))
{
    using (var transaction = connection.BeginTransaction(_capBus, autoCommit: false))
    {
        //your business code
        connection.Execute("insert into test(name) values('test')",
            transaction: (IDbTransaction)transaction.DbTransaction);

        _capBus.Publish("sample.rabbitmq.mysql", DateTime.Now);

        transaction.Commit();
    }
}

EntityFramework Core 方式同样简单,将 ICapPublisher.Publish 放在同一个 EF 事务中即可:

private readonly ICapPublisher _capBus;

using (var trans = dbContext.Database.BeginTransaction(_capBus, autoCommit: false))
{
    dbContext.Persons.Add(new Person() { Name = "ef.transaction" });

    _capBus.Publish("sample.rabbitmq.mysql", DateTime.Now);

    dbContext.SaveChanges();
    trans.Commit();
}

两份代码均来自对应存储文档(sqlserver.md、mysql.md、postgresql.md),是可直接复制运行的实战模板。仓库中的示例项目(如 Sample.RabbitMQ.MySql、Sample.Kafka.PostgreSql)也演示了同样的用法。

发送后:消息队列自身的持久化保障

消息成功进入消息队列后,CAP 不再依赖本地数据库保证该消息不丢失,而是借助消息队列自身的持久化能力。文档以 RabbitMQ 与 Kafka 两个最常用的传输为例进行了说明。

  • RabbitMQ:CAP 使用具有消息持久化功能的消费者队列。在 rabbitmq.md 中可以看到 CAP 创建的队列默认选项为 { Durable=true, Exclusive=false, AutoDelete=false },即默认队列就是持久化的。文档同时提醒存在例外情况(对应原文档 2.2.1 章节,主要指事务消息场景下的个别边界情况),实际使用时建议结合所选 RabbitMQ 版本与 CAP 传输文档确认。
  • Kafka:由于 Kafka 天生设计为使用文件进行消息持久化,消息进入 Kafka 之后由 Kafka 自身保证正确持久化而不丢失。

值得注意的是,发送前落库与发送后队列持久化是双重保险:即便消息已成功发布到队列,CAP 仍会在数据库中保留消息记录直到确认成功(成功消息默认 24 小时后由清理进程删除,见下文"消息生命周期"),以此支撑失败重试与最终一致性。

官方支持的存储提供程序与配置

CAP 支持以下几种具有事务支持的存储介质,分别对应独立的 NuGet 扩展包与配置扩展方法:

存储 NuGet 包 配置方法
SQL Server DotNetCore.CAP.SqlServer UseSqlServer()
MySQL DotNetCore.CAP.MySql UseMySql()
PostgreSQL DotNetCore.CAP.PostgreSql UsePostgreSql()
MongoDB DotNetCore.CAP.MongoDB UseMongoDB()
In-Memory Storage DotNetCore.CAP.InMemoryStorage UseInMemoryStorage()

所有关系型存储的接入方式一致:安装包后在 ConfigureServices 中调用 AddCap 并注册对应存储:

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddCap(x =>
    {
        x.UseMySql(opt => {
            //MySqlOptions
        });
        // x.UseXXX ...(传输等其他扩展)
    });
}

各存储的配置项与默认值汇总如下(来自 sqlserver.md、mysql.md、postgresql.md、mongodb.md):

SQL Server(DotNetCore.CAP.SqlServer)

配置项 说明 类型 默认值
Schema 数据库架构 string Cap
ConnectionString 数据库连接字符串 string (必填)

官方提示:当前使用 Microsoft.Data.SqlClient 作为数据库驱动程序,它代表 SQL Server 驱动的未来,官方已放弃 System.Data.SqlClient,建议使用 CAP 时切换过去。

MySQL(DotNetCore.CAP.MySql)

配置项 说明 类型 默认值
TableNamePrefix CAP 表名前缀 string cap
ConnectionString 数据库连接字符串 string null

PostgreSQL(DotNetCore.CAP.PostgreSql)

配置项 说明 类型 默认值
Schema 数据库架构 string cap
ConnectionString 数据库连接字符串 string (必填)
DataSource Npgsql 数据源(NpgsqlDataSource) DataSource —

MongoDB(DotNetCore.CAP.MongoDB,2.3+)

配置项 说明 类型 默认值
DatabaseName 数据库名称 string cap
DatabaseConnection 数据库连接字符串 string mongodb://localhost:27017
ReceivedCollection 接收消息集合名称 string cap.received
PublishedCollection 已发布消息集合名称 string cap.published
LockCollection 锁集合名称(启用存储锁时使用) string cap.lock

MongoDB 属于 NoSQL 存储,自 CAP 2.3 版本起支持。由于 MongoDB 从 4.0 版本才支持 ACID 事务,CAP 仅支持 4.0 以上的 MongoDB,且必须部署为集群——MongoDB 的 ACID 事务依赖集群才能使用。其事务发布写法基于 StartTransaction(_capBus, autoCommit: false):

// 注意:MongoDB 不能在事务中创建数据库和集合,需要先单独创建它们
//var mycollection = _client.GetDatabase("test").GetCollection<BsonDocument>("test.collection");
//mycollection.InsertOne(new BsonDocument { { "test", "test" } });

using (var session = _client.StartTransaction(_capBus, autoCommit: false))
{
    var collection = _client.GetDatabase("test").GetCollection<BsonDocument>("test.collection");
    collection.InsertOne(session, new BsonDocument { { "hello", "world" } });

    _capBus.Publish("sample.rabbitmq.mongodb", DateTime.Now);

    session.CommitTransaction();
}

In-Memory Storage(仅开发/测试)

要点 说明
适用场景 开发和测试环境
配置 x.UseInMemoryStorage();
代价 失去本地事务消息可靠性保证(不支持事务方式发送消息)
清理策略 内存中的发送成功消息,CAP 每 5 分钟清理一次

使用内存存储会丢失本地事务消息的可靠性保证,因此严禁在生产环境使用。

存储初始化与表结构自定义

CAP 启动后会初始化已发布消息和已接收消息的存储。物理名称和结构因存储提供程序而异,并可通过 TableNamePrefix(MySQL)或集合名称(MongoDB)等提供程序选项自定义;只有启用 UseStorageLock 时才会创建存储锁表。该行为由 IStorageInitializer.cs 接口定义,它暴露了 GetPublishedTableName()、GetReceivedTableName()、GetLockTableName() 三个取表名的方法以及 InitializeAsync 初始化方法。

如果你需要自定义表名,可以通过继承各存储的 StorageInitializer 并重写取表名方法实现(以 MySQL 为例):

public class MyTableInitializer : MySqlStorageInitializer
{
    public override string GetPublishedTableName()
    {
        //你的 发送消息表 名称
    }

    public override string GetReceivedTableName()
    {
        //你的 接收消息表 名称
    }
}

然后将你的实现注册到容器中:

services.AddSingleton<IStorageInitializer, MyTableInitializer>();

SQL Server、PostgreSQL 的用法完全一致,分别继承 SqlServerStorageInitializer、PostgreSqlStorageInitializer 即可。

消息存储字段:关系型表与 MongoDB 文档的逻辑结构

存储的 Content 值是 CAP 消息对象的序列化结果,其中包含消息标头和负载。它不是额外嵌套的包装对象,消息编号也不是 MongoDB ObjectId。关系型存储包含以下逻辑字段,具体数据库类型、索引、命名和提供程序专属字段因实现而异;MongoDB 保存对应的文档。

字段 说明
Id CAP 消息标识符(内置关系型存储中为 64 位整数)
Version CAP 配置的消息版本
Name 消息主题或名称
Content 序列化后的 CAP 消息,包含标头和负载
Retries 重试次数
Added 消息存储时间
ExpiresAt 可选的过期时间
StatusName 当前消息状态
Group 消费者组,仅接收消息包含此字段

这些字段可以从源码中得到印证:MediumMessage.cs 定义了消息的持久化载体(DbId、Origin、Content、Added、ExpiresAt、Retries),而 IDataStorage.MySql.cs 中的插入语句展示了实际字段:

INSERT INTO `{_pubName}`(`Id`,`Version`,`Name`,`Content`,`Retries`,`Added`,`ExpiresAt`,`StatusName`)
VALUES(@Id,'{Version}',@Name,@Content,@Retries,@Added,@ExpiresAt,@StatusName);

接收消息表则额外包含 Group 字段(见该文件约 339 行的 INSERT INTO {_recName} 语句),与文档表格中"Group 仅接收消息包含此字段"的说明一致。

StatusName 的状态机

StatusName.cs 定义了消息的完整状态枚举,这是理解存储层的关键:

枚举值 数值 含义
Failed -1 失败(超过重试阈值)
Scheduled 0 已调度,等待发送
Succeeded 1 已成功
Delayed 2 延迟消息
Queued 3 已入队(待调度发送)

消息的存储、重试查询与清理全部围绕该状态机进行:例如 IDataStorage.MySql.cs 中重试查询只捞取 StatusName IN ('Failed','Scheduled') 且 Retries 未达上限的消息;清理进程只删除 StatusName IN ('Succeeded','Failed') 且 ExpiresAt 已超时的记录。

消息生命周期:过期清理与重试参数

消息从入库到最终清理,由 CapOptions 中的一组参数控制,这些参数直接决定存储中消息的保留时间与重试行为:

参数 默认值 作用
Version v1 消息版本号(最长 20 字符),用于多实例/多版本部署时隔离数据
SucceedMessageExpiredAfter 86400(24 小时) 成功消息自动删除的间隔(秒)
FailedMessageExpiredAfter 1296000(15 天) 失败消息自动删除的间隔(秒)
FailedRetryCount 50 失败消息最大重试次数,达到阈值后标记为永久失败
FailedRetryInterval 60 重试处理器轮询失败消息的间隔(秒)
CollectorCleaningInterval 300(5 分钟) 清理处理器清理过期消息的间隔(秒)
FallbackWindowLookbackSeconds 240 重试处理器回看已调度/失败状态消息的时间窗(秒)
UseStorageLock false 是否启用分布式存储锁,启用后仅一个实例执行重试,防止重复处理,集群部署必需
SchedulerBatchSize 1000 单个调度周期最多获取的延迟/失败消息数量

其中 UseStorageLock 与存储层的锁表/锁集合(如 MongoDB 的 LockCollection)直接对应:启用后 CAP 才会创建锁表,并通过 IDataStorage.cs 中的 AcquireLockAsync、RenewLockAsync、ReleaseLockAsync 实现分布式互斥,确保多实例集群下只有单一实例执行重试任务。

社区支持的持久化扩展

除官方内置存储外,社区也为 CAP 贡献了多种持久化实现,可用于特殊数据库场景(以下信息来自 general.md,仓库不包含这些扩展的源码,需按需选用并自行验证):

存储选型建议与注意事项

综合文档与源码,给出如下选型与落地建议:

  1. 生产环境必须选择带事务支持的关系型存储或 MongoDB 集群,以获取"业务事务 + 消息落库"的强一致保证;In-Memory Storage 仅限开发/测试。
  2. 优先使用 ADO.NET 或 EF Core 事务发布模式,把 _capBus.Publish 放进业务事务,这是 CAP 最终一致性可靠性的根基。
  3. 多实例集群部署务必开启 UseStorageLock,否则多个实例可能并发重试同一批失败消息,破坏"仅一次"重试语义。
  4. 按业务需要调整过期清理参数(SucceedMessageExpiredAfter、FailedMessageExpiredAfter),平衡消息可追溯时长与存储占用;默认 24 小时/15 天的配置适合大多数场景。
  5. 升级 SQL Server 场景时确认驱动为 Microsoft.Data.SqlClient;使用 MongoDB 时确认版本 ≥ 4.0 且为集群部署。
  6. 表名/集合名冲突时,通过 TableNamePrefix、Schema、集合名称配置或重写 IStorageInitializer 自定义,避免多环境共用数据库时互相干扰。

关于各存储实际的表结构与迁移脚本,请继续查看 sqlserver.md、mysql.md、postgresql.md、mongodb.md 及对应提供程序源码(如 IDataStorage.MySql.cs、IStorageInitializer.MySql.cs)。

登录后查看全文
CAP