CAP 分布式事务框架 MySQL 持久化存储配置与事务消息实战指南

原创2026-10-06 22:17:031,353 阅读
文章标签:后端消息队列微服务可观测性

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 监控的底层实现。核心源码与示例的对应关系如下,便于继续深入研读:

登录后查看全文
CAP