CAP 分布式事务的消息持久化与存储选型完全指南
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,仓库不包含这些扩展的源码,需按需选用并自行验证):
- SQLite(@colinin):
DotNetCore.CAP.Sqlite - LiteDB(@maikebing):
CAP.Extensions - SQLite & Oracle(@cocosip):
CAP-Extensions - SmartSql(@xiangxiren):
SmartSql.CAP - DM(达梦数据库)(@findersky):
CAP - GaussDB(@JASONPANZ):
CAP
存储选型建议与注意事项
综合文档与源码,给出如下选型与落地建议:
- 生产环境必须选择带事务支持的关系型存储或 MongoDB 集群,以获取"业务事务 + 消息落库"的强一致保证;In-Memory Storage 仅限开发/测试。
- 优先使用 ADO.NET 或 EF Core 事务发布模式,把
_capBus.Publish放进业务事务,这是 CAP 最终一致性可靠性的根基。 - 多实例集群部署务必开启
UseStorageLock,否则多个实例可能并发重试同一批失败消息,破坏"仅一次"重试语义。 - 按业务需要调整过期清理参数(
SucceedMessageExpiredAfter、FailedMessageExpiredAfter),平衡消息可追溯时长与存储占用;默认 24 小时/15 天的配置适合大多数场景。 - 升级 SQL Server 场景时确认驱动为
Microsoft.Data.SqlClient;使用 MongoDB 时确认版本 ≥ 4.0 且为集群部署。 - 表名/集合名冲突时,通过
TableNamePrefix、Schema、集合名称配置或重写IStorageInitializer自定义,避免多环境共用数据库时互相干扰。
关于各存储实际的表结构与迁移脚本,请继续查看 sqlserver.md、mysql.md、postgresql.md、mongodb.md 及对应提供程序源码(如 IDataStorage.MySql.cs、IStorageInitializer.MySql.cs)。