CAP 分布式事务框架 MySQL 持久化存储配置与事务消息实战指南
CAP 分布式事务框架 MySQL 持久化存储配置与事务消息实战指南
本篇技术指南围绕 DotNetCore.CAP 的 MySQL 存储模块展开,系统讲解如何在 CAP 中接入 MySQL 作为消息持久化存储、如何利用本地事务与 Outbox 模式保证业务数据与消息的一致性,并深入源码剖析建表脚本、事务提交与消息刷盘的底层实现。读者读完可以独立完成 MySQL 存储的接入配置、自定义表名前缀与表名、以及基于 ADO.NET / EntityFramework 的事务消息发布。
安装 NuGet 扩展包
CAP 将存储层与传输层做了彻底解耦,MySQL 存储是独立的扩展包。要使用 MySQL 作为 CAP 消息的持久化存储,首先需要从 NuGet 安装扩展包:
Install-Package DotNetCore.CAP.MySql
安装后,在 Startup.cs(或 .NET 6+ 的 Program.cs)的 ConfigureServices 方法中通过 AddCap 注册 CAP 服务,并在配置 lambda 中调用 UseMySql 启用 MySQL 存储:
public void ConfigureServices(IServiceCollection services)
{
// ...
services.AddCap(x =>
{
x.UseMySql(opt=>
{
//MySqlOptions
});
// x.UseXXX ...
});
}
UseMySql 支持两种重载形式(见 CAP.Options.Extensions.cs):
// 方式一:直接传入连接字符串
x.UseMySql("Server=127.0.0.1;Database=cap;Uid=root;Pwd=your_password;");
// 方式二:通过 Action<MySqlOptions> 精细配置
x.UseMySql(opt =>
{
opt.ConnectionString = "Server=127.0.0.1;Database=cap;Uid=root;Pwd=your_password;";
opt.TableNamePrefix = "cap";
});
仓库中的示例项目 Sample.RabbitMQ.MySql/Program.cs 给出了完整的最小可运行组合——MySQL 存储搭配 RabbitMQ 传输与 Dashboard 监控:
builder.Services.AddCap(x =>
{
x.UseMySql(AppDbContext.ConnectionString);
x.UseRabbitMQ("localhost");
x.UseDashboard();
});
其中连接字符串常量定义在 AppDbContext.cs:
public const string ConnectionString = "Server=127.0.0.1;Database=cap;Uid=root;Pwd=my-secret-pw;";
配置项详解
UseMySql 的配置对象为 MySqlOptions,官方文档给出的核心配置项如下:
| NAME | DESCRIPTION | TYPE | DEFAULT |
|---|---|---|---|
| TableNamePrefix | Cap 表名前缀 | string | cap |
| ConnectionString | 数据库连接字符串 | string | null |
结合源码可以进一步确认这些配置的实际含义:
- TableNamePrefix:定义于基类 CAP.EFOptions.cs(
EFOptions),默认值为常量"cap"。它决定了 CAP 建表时使用的表名前缀,最终的表名形如cap.published、cap.received、cap.lock。 - ConnectionString:定义于 CAP.MySqlOptions.cs,是
MySqlOptions上新增的属性,存储 CAP 读写消息表所用的 MySQL 连接字符串,默认值为null(即必须显式配置)。
MySqlOptions 还继承了两个内部配置项:
- DbContextType:EF 上下文类型。当通过
UseEntityFramework<TContext>()注册时,ConfigureMySqlOptions 会从TContext的Database.GetConnectionString()自动提取连接字符串,覆盖ConnectionString配置;同时它会检查 DbContext 中是否直接使用了ICapPublisher,若检测到会抛出异常,提示改为直接使用存储扩展以避免循环引用。 - Version:内部数据版本标识,默认
"v1",写入每条消息记录的Version列,用于多版本消息的隔离检索。
此外还有 UseEntityFramework<TContext>() 扩展(见 CAP.Options.Extensions.cs),允许在已使用 EF Core 的项目中直接复用现有 DbContext 的连接配置,而无需重复书写连接字符串:
services.AddCap(x =>
{
x.UseEntityFramework<AppDbContext>();
x.UseRabbitMQ("localhost");
});
自定义表名称
默认情况下,CAP 会在 MySQL 中创建三张以 TableNamePrefix 为前缀的表。如果希望自定义消息表名称,可以通过重写 IStorageInitializer 的实现来做到。MySQL 的默认实现为 MySqlStorageInitializer,其中表名方法定义如下(见 IStorageInitializer.MySql.cs):
public virtual string GetPublishedTableName()
{
return $"{_options.Value.TableNamePrefix}.published";
}
public virtual string GetReceivedTableName()
{
return $"{_options.Value.TableNamePrefix}.received";
}
public virtual string GetLockTableName()
{
return $"{_options.Value.TableNamePrefix}.lock";
}
自定义表名的示例代码如下:
public class MyTableInitializer : MySqlStorageInitializer
{
public override string GetPublishedTableName()
{
//你的 发送消息表 名称
}
public override string GetReceivedTableName()
{
//你的 接收消息表 名称
}
}
然后将你的实现注册到容器中,替换默认注册:
services.AddSingleton<IStorageInitializer, MyTableInitializer>();
需要注意注册时机:MySqlCapOptionsExtension 在扩展内部通过 services.TryAddSingleton<IStorageInitializer, MySqlStorageInitializer>() 注册默认实现(见 CAP.MySqlCapOptionsExtension.cs),TryAdd 意味着如果你的容器中已经注册了自定义实现,默认实现将不会生效,因此上述自定义注册可以与 AddCap 并存且优先级更高。
使用事务发布消息
CAP 的核心价值在于 Outbox 模式:业务数据写入与消息发布处于同一个本地数据库事务中,保证"要么都成功,要么都失败",从而在微服务架构下实现基于最终一致性的事件总线。
ADO.NET
使用 MySqlConnection 时,通过 CAP 提供的 BeginTransaction 扩展方法开启事务,业务 SQL 与 Publish 共享该事务:
private readonly ICapPublisher _capBus;
using (var connection = new MySqlConnection(AppDbContext.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();
}
}
这里的 BeginTransaction 扩展定义于 ICapTransaction.MySql.cs,其实现要点如下:
- 若连接处于关闭状态会自动
Open(); - 调用
dbConnection.BeginTransaction(isolationLevel)创建真正的数据库事务; - 通过
ActivatorUtilities.CreateInstance<MySqlCapTransaction>创建 CAP 事务包装器,并把AutoCommit设为传入值(默认false)。
ICapPublisher.Publish 内部会把消息写入 cap.published 表(见 IDataStorage.MySql.cs 的 StoreMessageAsync,初始状态为 Scheduled),写入操作复用当前事务连接,因此只有 transaction.Commit() 成功后消息才会真正落库;一旦提交,CAP 的事务实现 MySqlCapTransaction.Commit() 会先提交数据库事务,再调用 Flush() 把已落库的消息发送到消息队列(MQ),确保"先落库、后发送"的顺序。
BeginTransaction 同样提供了 BeginTransactionAsync 异步重载,支持指定 IsolationLevel 隔离级别。
EntityFramework
使用 EF Core 时,通过 dbContext.Database.BeginTransaction(_capBus, autoCommit: false) 开启 CAP 事务,示例代码如下:
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();
}
EF 场景下 BeginTransaction(DatabaseFacade database, ICapPublisher publisher, bool autoCommit = false) 扩展(见 ICapTransaction.MySql.cs)返回的是 IDbContextTransaction 类型的 CapEFDbTransaction 包装器(见 IDbContextTransaction.CAP.cs),它内部委托给 MySqlCapTransaction:
Commit()/CommitAsync()提交底层IDbContextTransaction后立即调用Flush()/FlushAsync(),将消息刷出到消息队列;Rollback()/RollbackAsync()则仅回滚底层事务,不触发消息发送;MySqlCapTransaction的Commit会根据底层事务的实际类型(IDbTransaction或IDbContextTransaction)分发提交逻辑,见 ICapTransaction.MySql.cs。
源码级原理:建表脚本与存储锁
CAP 在首次启动时会由 MySqlStorageInitializer.InitializeAsync 自动执行建表脚本(见 IStorageInitializer.MySql.cs),无需手工建表。脚本包含两张核心消息表:
cap.received(接收消息表),用于记录订阅方收到的消息:
CREATE TABLE IF NOT EXISTS `cap.received` (
`Id` bigint NOT NULL,
`Version` varchar(20) DEFAULT NULL,
`Name` varchar(400) NOT NULL,
`Group` varchar(200) DEFAULT NULL,
`Content` longtext,
`Retries` int(11) DEFAULT NULL,
`Added` datetime NOT NULL,
`ExpiresAt` datetime DEFAULT NULL,
`StatusName` varchar(50) NOT NULL,
PRIMARY KEY (`Id`),
INDEX `IX_Version_ExpiresAt_StatusName` (`Version`, `ExpiresAt`, `StatusName`),
INDEX `IX_ExpiresAt_StatusName` (`ExpiresAt`, `StatusName`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
cap.published(发送消息表),用于记录发送方发布的消息:
CREATE TABLE IF NOT EXISTS `cap.published` (
`Id` bigint NOT NULL,
`Version` varchar(20) DEFAULT NULL,
`Name` varchar(200) NOT NULL,
`Content` longtext,
`Retries` int(11) DEFAULT NULL,
`Added` datetime NOT NULL,
`ExpiresAt` datetime DEFAULT NULL,
`StatusName` varchar(40) NOT NULL,
PRIMARY KEY (`Id`),
INDEX `IX_Version_ExpiresAt_StatusName` (`Version`, `ExpiresAt`, `StatusName`),
INDEX `IX_ExpiresAt_StatusName` (`ExpiresAt`, `StatusName`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
当 CapOptions.UseStorageLock 开启时(存储级锁),还会额外创建 cap.lock 锁表,并预置发送重试与接收重试两条锁记录,供 CAP 的分布式轮询调度(SchedulerBatchSize 批量调度、延迟消息、失败重试)在多实例部署时通过 AcquireLockAsync / RenewLockAsync / ReleaseLockAsync 协调互斥(见 IDataStorage.MySql.cs)。
此外,IsSupportSkipLocked() 会根据服务端版本决定是否使用 FOR UPDATE SKIP LOCKED 语法:MySQL 8.0+、MariaDB 10.6+(或 10.0 以上大版本)支持该语法,用于调度与过期清理时跳过被其他实例锁定的行,提升并发调度的吞吐能力。
测试项目 MySqlStorageTest.cs 对建表结果做了直接验证——断言数据库中存在 cap.published 与 cap.received 两张表,可作为接入 MySQL 存储后自检建表是否成功的参考。
监控与 Dashboard 支持
MySQL 存储实现同时提供 IMonitoringApi(见 IMonitoringApi.MySql.cs),配合 Dashboard 扩展包(x.UseDashboard())可以在浏览器中查看:
- 统计数据:发布/接收的成功、失败、延迟消息数量;
- 消息查询:按状态、名称、Group、内容关键词分页检索发布与接收消息;
- 时间线统计:最近 24 小时逐小时的成功/失败消息分布;
- 单条消息详情:查看消息内容、重试次数、入库时间与过期时间。
这使得 MySQL 不仅是消息的持久化存储,同时也天然成为 CAP 消息的可观测性数据源,便于排查重试、延迟与失败消息的链路问题。
小结
本文以 CAP 官方 MySQL 存储文档为主线,完成了从扩展包安装、UseMySql 配置、配置项语义解析、自定义表名,到 ADO.NET / EF Core 两种事务发布消息的完整实操覆盖,并结合仓库源码剖析了建表脚本、存储锁、事务提交后 Flush 刷盘以及 Dashboard 监控的底层实现。核心源码与示例的对应关系如下,便于继续深入研读: