CAP 消息幂等性深度解析:交付语义、重试机制与消费端幂等设计实践
CAP 消息幂等性深度解析:交付语义、重试机制与消费端幂等设计实践
CAP(DotNetCore.CAP)是一套基于最终一致性的分布式事务解决方案,同时也内置了基于 Outbox 模式的事件总线能力。在基于消息的分布式系统中,"消息被重复处理"几乎是无法避免的常态,因此消费端的幂等性设计是 CAP 使用者绕不开的核心议题。本文以 CAP 官方文档《幂等性》为主体,结合仓库中重试处理器与存储清理的源码实现,系统讲解消息交付的三种语义、CAP 为何选择 At Least Once、框架为何不内置严格幂等,以及两种在业务代码中落地幂等的经典方案,帮助读者在自己的 CAP 消费端写出安全、可重复执行的处理逻辑。
幂等性的基本概念
幂等性(Idempotence)是指在分布式环境下,对同一个操作执行多次与执行一次所产生的结果是一致的。当我们谈论消息幂等时,一般是指可以重复处理传递的消息,而不会产生意外的结果——即同一条消息被 Consumer 消费一次还是多次,业务系统最终的状态都应该相同。
需要明确的是,幂等性是一个业务层面的属性,它的实现往往依赖业务数据自身的特性(如唯一约束、状态机)或额外的跟踪机制,而非消息中间件本身的能力。
消息交付的三种保证语义
在讨论幂等之前,首先要理解消费端的消息交付(Delivery)语义。由于 CAP 没有使用 MS DTC 或其他类型的 2PC 分布式事务机制,因此无法做到严格意义上"每条消息只被处理一次"的交付保证。在基于消息的系统中,一般存在以下三种可能:
| 语义 | 说明 |
|---|---|
| Exactly Once(仅有一次) | 每条消息恰好被处理一次,带 * 号,实际场景中很难达到 |
| At Most Once(最多一次) | 每条消息最多被处理一次,可能丢失消息 |
| At Least Once(最少一次) | 每条消息至少被处理一次,可能重复处理 |
其中"Exactly 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 采用本地消息表(Outbox)与最终一致性方案的出发点。
CAP 的交付保证选择:At Least Once
在 CAP 中,采用的交付保证为 At Least Once(最少一次)。
由于 CAP 具有临时存储介质(数据库表),从理论上或许可以做到 At Most Once,但为了严格保证消息不会丢失,CAP 没有提供相关的功能或配置来切换语义。也就是说:只要你使用 CAP,就必须接受"消息可能被重复消费"这一前提,并在此基础上设计自己的消费端幂等。
这一选择在源码中也有印证:CAP 内置的重试处理器会对失败消息进行周期性的重新派发。在 IProcessor.NeedRetry.cs 中,MessageNeedToRetryProcessor 每隔 FailedRetryInterval 秒就会通过 IDataStorage.GetPublishedMessagesOfNeedRetry / GetReceivedMessagesOfNeedRetry 从存储中取出处于"待重试"状态的消息,并分别调用 _dispatcher.EnqueueToPublish / EnqueueToExecute 重新入队投递,直到达到 FailedRetryCount(默认 50 次)上限为止。重试处理器本身还被 InfiniteRetryProcessor 包裹,即使处理过程抛出异常也会在等待 2 秒后继续重试,保证重试逻辑自身不中断——这一系列机制共同确保了消息"至少被处理一次"。
为什么 CAP 没有内置严格幂等?
CAP 的消费端并不直接提供"消息去重"能力,官方文档给出了四个层面的原因,理解这些原因有助于你做出正确的架构决策。
1. 消息写入成功,但执行 Consumer 方法失败
消息写入成功了,但此时执行 Consumer 方法失败了。执行 Consumer 方法失败的原因非常多,如果不知道具体的业务场景而盲目进行重试或者不进行重试,都是不正确的选择。
举个例子:假如消费者是扣款服务,如果是执行扣款成功了,但是在写扣款日志的时候失败了,此时 CAP 会判断为消费者执行失败并进行重试。如果客户端自己没有保证幂等性,框架对其进行重试,这里势必会造成多次扣款的严重后果。框架无法判断"失败"发生在业务副作用之前还是之后,因此不敢替业务做决定。
2. 执行 Consumer 方法成功,但又收到了同样的消息
此场景也是可能存在的:假如开始的时候 Consumer 已经执行成功了,但由于某种原因(如 Broker 宕机恢复等)又收到了相同的消息。CAP 在收到 Broker 消息后会认为这是一个新的消息,会对 Consumer 再次执行。由于是新消息,此时 CAP 也无法做到幂等——Broker 侧的重放与业务侧的"已处理"状态之间缺少关联纽带。
3. 目前的数据存储模式无法做到幂等
由于 CAP 存储消息的表对于成功消费的消息会在过期后删除,因此对于一些历史性消息无法做到幂等操作。这里的历史性指的是:假如 Broker 由于某种原因维护了,或者是人工处理的一些消息。以 CAP.Options.cs 中的默认配置为例,成功消息的过期时间 SucceedMessageExpiredAfter 默认为 86,400 秒(24 小时),失败消息的过期时间 FailedMessageExpiredAfter 默认为 15 天,过期消息会由清理处理器定期移除。一旦成功的消费记录被清理,面对 Broker 侧重放的历史消息,CAP 就没有任何依据判断"这条消息曾经被处理过"。
4. 业界普遍做法
许多基于事件驱动的框架都要求用户来保证幂等性操作,例如 ENode、RocketMQ 等。从实现的角度来说,CAP 可以做一些比较不严格的幂等,但严格的幂等是无法做到的。因此,将幂等视为"消费端的业务责任"是业界共识,CAP 选择把这一职责交给使用者,换取框架本身的简洁与可靠。
消费端幂等的两种实现思路
既然 CAP 不内置幂等,那么业务侧如何落地?官方文档给出了两种经典思路:利用业务对象自身的幂等能力(自然幂等),或者引入独立的消息跟踪器(显式幂等)。
以自然的方式处理幂等消息
通常情况下,保证消息被执行多次而不会产生意外结果,最自然的方式是采用操作对象自带的一些幂等功能。比如数据库提供的 INSERT ON DUPLICATE KEY UPDATE,或者是采用类似的程序判断行为:
- 关系型数据库的唯一索引 +
INSERT ... ON DUPLICATE KEY UPDATE; - MongoDB 的
_id唯一约束 + upsert 操作; - 业务表设计中的"状态机"约束:只有"待处理"状态的消息才能被推进到"已处理"状态,重复消息到达时因为状态不匹配而被直接忽略。
这种方式的优点是零额外组件、与业务模型深度耦合,缺点是需要你的业务操作天然具备"重复执行无副作用"的性质。
显式处理幂等消息:IMessageTracker 消息跟踪器
另外一种处理幂等性的方式,就是在消息传递的过程中传递消息 ID,然后由单独的消息跟踪器(Message Tracker)来处理。例如你使用具有事务数据存储的 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);
}
核心逻辑分三步:
- 查重:进入处理方法后,先用
HasProcessed(message.Id)检查该消息是否已经处理过,若已处理则直接返回,避免重复执行业务副作用; - 执行业务:只有未处理过的消息才进入实际业务逻辑;
- 标记完成:业务执行成功后调用
MarkAsProcessed(messageId)记录该消息 ID,供后续重复消息查重使用。
至于 IMessageTracker 的实现,可以使用诸如 Redis 或者数据库等存储消息 Id 和对应的处理状态。需要注意的是,查重与"标记完成"之间存在天然的时间窗口,若要求极高的一致性,应当让标记动作与业务副作用处于同一事务中(例如业务表与消息跟踪表共用同一个数据库事务),这也是 Outbox 模式思想的延伸;若使用 Redis 等外部存储,则要评估该窗口内重复执行的容忍度。
从实践角度看,还有两点值得注意:
- 消息 ID 必须是全局唯一且稳定的,建议在发布端生成(例如用 CAP 的雪花 ID 能力)并随消息体一起传递,避免在消费端临时生成;
- 消息跟踪表建议对消息 ID 建立唯一索引,防止并发场景下同一个消息被两个线程同时处理;利用数据库唯一约束,可以让"标记完成"在冲突时自然退化为幂等。
与幂等性相关的 CAP 配置速查
理解幂等性之后,再回看 CAP 的重试与清理机制,相关的核心配置项如下(默认值见 CAP.Options.cs):
| 配置项 | 默认值 | 说明 |
|---|---|---|
FailedRetryInterval |
60(秒) | 重试处理器轮询失败消息的间隔 |
FailedRetryCount |
50(次) | 失败消息(发布与订阅)的最大重试次数,超过后标记为永久失败并停止重试 |
SucceedMessageExpiredAfter |
86,400 秒(24 小时) | 成功消费的消息在存储中的保留时长,到期后由清理处理器删除 |
FailedMessageExpiredAfter |
15 天 | 失败消息的保留时长,到期后清理 |
FallbackWindowLookbackSeconds |
240(秒) | 重试处理器回看的时间窗口,用于兜底时钟偏差导致的状态消息漏检 |
UseStorageLock |
false | 是否启用分布式存储锁,启用后集群中仅单实例执行消息重试,防止重复派发(与消费端幂等相互补充) |
其中 UseStorageLock 的语义与幂等密切相关:在集群部署时,若不开启存储锁,多个实例可能同时对同一批失败消息发起重试,造成同一消息被重复派发。开启后,重试过程会通过 AcquireLockAsync / ReleaseLockAsync(见 IProcessor.NeedRetry.cs)保证只有单个实例执行重试,从"派发源头"降低了重复处理的概率——但它依然不能替代消费端的业务幂等,因为 Broker 本身的重复投递(如宕机恢复后的重放)并不会被这把锁拦截。
小结
- CAP 基于 Outbox 与最终一致性方案,消费端交付语义为 At Least Once,消息可能重复,但不会丢失;
- CAP 从框架层面不提供严格的消费幂等,原因是消费失败的业务不确定性、Broker 重放、成功消息过期清理以及业界惯例四个层面的客观限制;
- 消费端幂等是使用者的责任,推荐两种落地方式:自然幂等(利用唯一约束、
INSERT ON DUPLICATE KEY UPDATE等业务自身能力)与显式幂等(消息 ID +IMessageTracker消息跟踪器); - 结合 CAP 的重试处理器(IProcessor.NeedRetry.cs)与消息清理配置(CAP.Options.cs),合理设置重试次数、成功消息保留时长与存储锁,可以在框架层面进一步降低重复处理的概率,但最终的业务一致性仍需消费端幂等来兜底。
把"消费端幂等"当作 CAP 使用规范的一部分纳入团队约定,配合事务性消息跟踪表,你就能在 At Least Once 的交付语义下,稳妥地实现业务上的"Exactly Once"效果。