CAP 分布式事件总线中的消息幂等性:交付保证、重试机制与消费端幂等实践指南

原创2026-09-28 09:55:522,195 阅读
文章标签:后端消息路由微服务

CAP 分布式事件总线中的消息幂等性:交付保证、重试机制与消费端幂等实践指南

在基于最终一致性的事件总线 CAP(基于 Outbox 模式)中,消费端收到同一条消息多次是常态而非异常:由于 CAP 不依赖 MS DTC 等 2PC 分布式事务,系统只能保证"至少一次(At Least Once)"交付,消费者必须自行保证消息处理的幂等性。本文围绕官方指南 幂等性 展开,先讲清消息交付的三种语义,再从源码层面解释 CAP 为什么不做严格幂等、失败消息的重试链路如何运转,最后给出"自然幂等"与"显式幂等(IMessageTracker)"两种可落地的消费端幂等方案,帮助你在自己的订阅者代码中避免重复扣款、重复下单等副作用。

交付保证:消息系统能承诺什么

在讨论幂等性之前,需要先明确消费端的消息交付语义。基于消息的系统中存在以下三种可能:

  • Exactly Once(仅有一次):每条消息恰好被处理一次。带 * 号表示在实际场景中很难达到,因为消息系统与业务系统之间无法形成原子提交/回滚。
  • At Most Once(最多一次):消息要么被处理一次,要么根本不被接收,存在消息丢失风险。
  • At Least Once(最少一次):每条消息至少被接收一次,出现故障时可能被接收多次,存在重复处理风险。

At Most Once:先取消息,后处理

"最多一次"保证可能来自你的消息系统,代码按以下顺序执行操作:

1. 从队列移除消息
2. 开始一个工作事务
3. 处理消息 ( 你的代码 )
4. 是否成功 ?
    Yes:
        1. 提交工作事务
    No:
        1. 回滚工作事务
        2. 将消息发回到队列。

正常情况下工作事务会被提交,一切正常。然而,第 1 步之后出现异常、把消息放回队列时遭遇网络问题、或者宕机重启等情况都可能发生。使用这个协议,你将冒着丢失消息的风险——如果业务可以接受消息丢失,那它没有问题。

At Least Once:先抢占,后确认

"至少一次"交付保证要求消息队列系统支持事务或 ACK 机制,例如传统的 begin-commit-rollback 协议(MSMQ 如此),或者是 receive-ack-nack 协议(RabbitMQ、Azure Service Bus 等如此)。大致步骤如下:

1. 抢占队列中的消息。
2. 开始一个工作事务
3. 处理消息 ( 你的代码 )
4. 是否成功 ?
    Yes:
        1. 提交工作事务
        2. 从队列删除消息
    No:
        1. 回滚工作事务
        2. 从队列释放抢占的消息

当处理失败或抢占消息超时时,消息总是能够再次被接收到,以保证工作事务最终提交成功。代价是:消息可能被重复处理,这就是幂等性问题产生的根源。

什么是"工作事务"?

上面所说的"工作事务"并不是特指关系型数据库中的事务,而是一个概念——即"执行代码的原子性"。它可以是传统的 RDBMS 事务,也可以是 MongoDB 事务,甚至是一次交易。在这里它代表一个执行单元,一个概念性的事实,用于支撑前面提到的"仅交付一次"问题。通常,不可能做到消息系统的事务与工作事务形成原子性来一起提交或回滚,这正是分布式环境下消息重复无法从协议层面消除的原因。

CAP 中的交付保证:At Least Once

在 CAP 中,采用的交付保证为 At Least Once。虽然 CAP 拥有临时存储介质(数据库表),理论上也许可以做到 At Most Once,但为了严格保证消息不丢失,CAP 没有提供相关功能或配置来切换交付语义。

这套"至少一次"保证在源码中有完整支撑:

  • 消费端收到消息后,消息会先落库为 Received 状态,再由调度器交给订阅者执行。订阅者执行成功时调用 ChangeReceiveStateAsync(message, StatusName.Succeeded) 标记为成功,并给消息设置过期时间 ExpiresAt = DateTime.Now.AddSeconds(SucceedMessageExpiredAfter);执行失败则标记为 Failed 并设置重试次数与过期时间 ExpiresAt = message.Added.AddSeconds(FailedMessageExpiredAfter),见 ISubscribeExector.Default.cs。
  • 后台的 MessageNeedToRetryProcessor 会以 FailedRetryInterval(默认 60 秒)为周期,调用 GetReceivedMessagesOfNeedRetry 捞取需要重试的消息,并 EnqueueToExecute 重新投递给订阅者执行。
  • 由于数据库表有 ExpiresAt 字段,由 CollectorProcessor 定期清理过期数据(默认每 CollectorCleaningInterval 秒,批量 1000 条)。整个"先落库、后确认、失败重试"的闭环保证了消息不丢失,也因此带来了重复投递。

重试相关的核心配置

重试行为由 CapOptions 中的参数控制,常用配置项如下:

配置项 默认值 说明
FailedRetryCount 50 失败消息(发布与订阅)的最大重试次数,达到阈值后标记为永久失败,不再重试
FailedRetryInterval 60(秒) 重试处理器扫描失败消息的时间间隔
SucceedMessageExpiredAfter 86400(24 小时) 成功处理的消息在表中保留的时间,过期后被清理
FailedMessageExpiredAfter 1296000(15 天) 失败消息在表中保留的时间,过期后被清理
CollectorCleaningInterval 300(秒) 清理过期消息的轮询间隔
FailedThresholdCallback null 消息重试达到 FailedRetryCount 上限仍未成功时触发的回调,可在此做告警或补偿

配置示例:

services.AddCap(x =>
{
    x.FailedRetryCount = 10;
    x.FailedRetryInterval = 30;
    x.FailedThresholdCallback = info =>
    {
        // 重试耗尽后的告警或人工补偿处理
        var message = info.Message;
    };
});

注意:官方文档曾描述"成功消费的消息会于 1 个小时后删除",而当前仓库源码中的默认值已是 SucceedMessageExpiredAfter = 24 * 3600(24 小时),即成功消息默认保留 24 小时后由 CollectorProcessor 清理,实际保留时长以你在 CapOptions 中的配置为准。

为什么 CAP 没有实现幂等?

CAP 没有内置严格的幂等能力,主要原因有四:

1. 消息写入成功,但执行 Consumer 方法失败

执行 Consumer 方法失败的原因非常多,如果不知道具体场景就盲目重试或不重试都是不正确的选择。举个例子:假如消费者是扣款服务,如果扣款已经成功,但在写扣款日志时失败,此时 CAP 会判断消费者执行失败并触发重试。如果客户端自己没有保证幂等性,框架的重试势必会造成多次扣款,产生严重后果。

2. Consumer 执行成功,但又收到了同一条消息

此场景同样存在:假如 Consumer 已经执行成功,但由于 Broker 宕机恢复等原因,CAP 又收到了相同的消息。CAP 在收到 Broker 消息后会将其视为一条新消息,对 Consumer 再次执行。由于是"新消息",此时 CAP 无法做到幂等。每条消息都带有 cap-msg-id(Headers.MessageId)作为唯一标识,见 Headers.cs,但 CAP 默认不会用它去做去重判断。

3. 当前的数据存储模式无法做到幂等

CAP 存储消息的表对成功消费的消息会在 SucceedMessageExpiredAfter 后删除(默认 24 小时),失败消息在 FailedMessageExpiredAfter 后删除(默认 15 天),因此对历史性消息(例如 Broker 维护期间滞留或人工处理的消息)无法回溯做幂等判断。

4. 业界做法

许多基于事件驱动的框架都要求用户来保证幂等性操作,例如 ENode、RocketMQ 等。从实现角度来说,CAP 可以做比较宽松的幂等,但严格的幂等无法做到——因此把幂等责任交还给业务方是更务实的选择。

以自然的方式处理幂等消息

通常情况下,保证消息被重复执行而不会产生意外结果的最自然方式,是采用操作对象自带的一些幂等功能。例如:

  • 数据库提供的 INSERT ON DUPLICATE KEY UPDATE(MySQL)或 ON CONFLICT ... DO NOTHING(PostgreSQL);
  • 采用"先查询再插入/更新"的类型化程序判断行为;
  • 使用具备天然幂等语义的存储操作(如 Redis 的 SETNX、幂等的状态机更新)。

这类方案的核心思想是:把"重复执行无害"建立在底层存储的约束之上,而不是依赖消息框架。

显式处理幂等消息:IMessageTracker

另一种处理幂等性的方式,是在消息传递过程中传递消息 ID,然后由单独的消息跟踪器(Message Tracker)来记录处理状态。CAP 的消息头中天然携带 cap-msg-id(Headers.MessageId),消费者可以直接读取该 ID 作为去重键。例如,使用具有事务数据存储的 IMessageTracker 来跟踪消息 ID,订阅者代码可能长这样:

readonly IMessageTracker _messageTracker;

public SomeMessageHandler(IMessageTracker messageTracker)
{
    _messageTracker = messageTracker;
}

[CapSubscribe]
public async Task Handle(SomeMessage message)
{
    if (await _messageTracker.HasProcessed(message.Id))
    {
        return;
    }

    // do the work here
    // ...

    // remember that this message has been processed
    await _messageTracker.MarkAsProcessed(messageId);
}

至于 IMessageTracker 的实现,可以使用 Redis 或者数据库等存储消息 ID 和对应的处理状态。需要留意的是:

  • 幂等判断与业务写入最好处于同一事务:如果 MarkAsProcessed 与业务操作不在同一个原子单元内,仍然可能出现"业务执行成功但标记丢失"或"标记成功但业务未提交"的窗口期,导致重复处理。因此推荐将去重标记与业务数据更新放在同一个数据库事务中完成。
  • 结合重试机制理解:当订阅者抛出异常时,CAP 会按 FailedRetryCount 重试,见 ISubscribeExector.Default.cs。此时 HasProcessed 应能区分"处理中/处理成功/处理失败"等多种状态,避免把"处理中"误判为"已成功"而跳过重试;同时要在业务代码里把可能重复的副作用(扣款、发短信、写库存)全部纳入幂等保护。

消息 ID 从哪来

CAP 在发布消息时会在消息头写入 cap-msg-id(MessageId),且该 ID "可以由发布时显式指定,或由 CAP 自动分配"(见 Headers.cs 的说明)。订阅者侧可以通过 message.Headers[Headers.MessageId] 或消息对象上的对应属性取得该 ID,将其持久化到去重表即可实现跨 Broker 重复投递的拦截。

小结

  • CAP 基于 Outbox 模式的存储机制保证了消息不丢失,交付语义为 At Least Once,因此消费端可能收到重复消息;
  • 由于失败原因多样、Broker 可能重复投递、历史消息会被过期清理等原因,CAP 不提供严格幂等,而是遵循业界惯例把幂等责任交给消费者;
  • 消费端幂等有两种主流做法:自然幂等(借助数据库约束或幂等操作让重复执行无害)与显式幂等(用 IMessageTracker 记录 cap-msg-id 的处理状态);
  • 重试次数、重试间隔、消息保留时长等参数可在 CapOptions 中调整,合理配置它们可以缩短重复窗口,但永远无法替代业务侧的幂等设计。

编写幂等逻辑时请牢记:去重记录与业务副作用必须在同一原子单元内提交,这是"显式幂等"方案真正可靠的前提。

登录后查看全文
CAP