一个内存队列只要十几行代码。但要让队列具备生产环境所需的可靠性,难点在于:消费者并不总能正常处理完每一条消息。
消费者可能处理到一半崩溃,可能因为失败需要重试,也可能处理太慢,以至于消息被重新投递。还有一种情况:业务已经处理成功,ACK 却丢了。Broker 的许多复杂度,都来自对这些异常情况的语义设计。
下面用 Rust 从零搭建一个消息队列 Broker,逐步讨论确认、重投、死信和持久化。代码以说明设计为主,部分辅助类型和方法需要结合实际工程补全。
从最简单的开始
pub struct NaiveQueue {
items: std::collections::VecDeque<Vec<u8>>,
}
impl NaiveQueue {
pub fn push(&mut self, msg: Vec<u8>) {
self.items.push_back(msg);
}
pub fn pop(&mut self) -> Option<Vec<u8>> {
self.items.pop_front()
}
}
问题很清楚:消息被 pop 取走后就从队列中消失了。如果消费者处理失败,这条消息便无法再次投递。这属于“至多一次”(at-most-once)投递:消息可能丢失,但不会因为队列重投而重复消费。
要支持“至少一次”(at-least-once),就需要 ACK 机制,让 Broker 知道消费者是否完成了处理。
核心设计:三态消息
一条消息在 Broker 中可以处于三种状态:
Ready:可以被消费。
InFlight:已被消费者取走,等待 ACK。
Acked:处理完成,可以删除。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MsgState {
Ready,
InFlight,
Acked,
}
pub struct Message {
pub id: u64,
pub body: Vec<u8>,
pub state: MsgState,
/// 投递次数,用来判断是否进入死信队列
pub delivery_count: u32,
/// InFlight 状态的截止时间,超时后重回 Ready
pub visible_at: std::time::Instant,
/// 正在处理消息的消费者
pub consumer: Option<String>,
}
visible_at 用来实现可见性超时(visibility timeout),这也是 SQS 中的核心概念。它解决的是消费者取走消息后崩溃,消息一直停留在 InFlight 状态的问题:
- T+0:消费者 A 取走消息,
visible_at 设为 T+30 秒。
- T+10 秒:A 崩溃,没有发送 ACK。
- T+30 秒:Broker 检查到消息超时,将其改回
Ready。
- T+31 秒:消费者 B 取到这条消息。
代价是消息可能被重复投递。这也是“至少一次”的关键取舍:在相应的可靠性条件成立时,消息不会因单次处理失败而丢失,但可能被处理多次。
消息队列的语义是一条谱系:at-most-once 可能丢消息,at-least-once 可能重复,exactly-once 则需要结合幂等或事务,明确端到端的处理边界。
Broker 主体
use std::collections::HashMap;
use std::sync::{Condvar, Mutex};
pub struct Broker {
inner: Mutex<Inner>,
/// 有新消息时唤醒等待的消费者
not_empty: Condvar,
}
struct Inner {
/// 消息存储:id -> Message
messages: HashMap<u64, Message>,
/// 就绪队列,只存 id
ready: std::collections::VecDeque<u64>,
/// 下一个要分配的消息 id
next_id: u64,
/// 死信队列
dead_letters: Vec<Vec<u8>>,
}
impl Inner {
fn enqueue(&mut self, body: Vec<u8>) -> u64 {
let id = self.next_id;
self.next_id += 1;
self.messages.insert(
id,
Message {
id,
body,
state: MsgState::Ready,
delivery_count: 0,
visible_at: std::time::Instant::now(),
consumer: None,
},
);
self.ready.push_back(id);
id
}
}
为什么 ready 只存 ID,而不存消息本体?因为消息状态会在 Ready、InFlight 等状态之间变化。只存 ID,可以让 messages 表成为状态的唯一存储位置,避免队列和表中的状态不一致。
消费:取走并设置可见性超时
pub const DEFAULT_VISIBILITY_TIMEOUT: std::time::Duration =
std::time::Duration::from_secs(30);
impl Broker {
pub fn receive(&self, consumer: &str) -> Option<Receipt> {
let mut inner = self.inner.lock().unwrap();
// 先把超时的 InFlight 消息放回 ready
inner.requeue_expired();
let id = inner.ready.pop_front()?;
let msg = inner.messages.get_mut(&id)?;
msg.state = MsgState::InFlight;
msg.delivery_count += 1;
msg.visible_at = std::time::Instant::now() + DEFAULT_VISIBILITY_TIMEOUT;
msg.consumer = Some(consumer.to_string());
Some(Receipt {
id,
body: msg.body.clone(),
delivery_count: msg.delivery_count,
})
}
}
每次 receive 前先调用 requeue_expired,属于惰性清理:不依赖后台定时器,只要消费者再次取消息,就会检查并回收超时消息。
impl Inner {
fn requeue_expired(&mut self) {
let now = std::time::Instant::now();
// 收集所有超时的 InFlight 消息
let expired: Vec<u64> = self
.messages
.values()
.filter(|m| m.state == MsgState::InFlight && m.visible_at <= now)
.map(|m| m.id)
.collect();
for id in expired {
if let Some(msg) = self.messages.get_mut(&id) {
msg.state = MsgState::Ready;
msg.consumer = None;
// delivery_count 不重置,否则可能无限重投
}
self.ready.push_back(id);
}
}
}
delivery_count 不能在重投时重置。否则,一条始终处理失败的消息会不断经历“投递 → 超时 → 投递”,无法根据累计次数进入死信队列。
重投计数只增不减,是按投递次数限制重试的前提。
ACK:确认完成
pub struct Receipt {
pub id: u64,
pub body: Vec<u8>,
pub delivery_count: u32,
}
impl Broker {
pub fn ack(&self, receipt: &Receipt, success: bool) -> Result<(), BrokerError> {
let mut inner = self.inner.lock().unwrap();
let msg = inner
.messages
.get_mut(&receipt.id)
.ok_or(BrokerError::UnknownMessage)?;
match msg.state {
MsgState::Acked => return Ok(()),
MsgState::Ready => return Ok(()),
MsgState::InFlight => {}
}
if success {
msg.state = MsgState::Acked;
} else {
// 显式失败:立即重回就绪队列
msg.state = MsgState::Ready;
msg.consumer = None;
inner.ready.push_back(receipt.id);
}
inner.gc();
Ok(())
}
}
重复 ACK 需要考虑幂等性。例如,消费者处理成功并发送 ACK,但由于网络抖动,没有收到确认结果,于是再次发送 ACK。如果 Broker 把第二次请求当成处理失败,消费者可能误判并重复执行业务逻辑。
上面的代码展示了对 Acked 状态重复 ACK 返回成功的思路,但仍有两个需要补齐的边界:
- 如果
gc 已删除消息,重复 ACK 会得到 UnknownMessage;要实现稳定的幂等确认,需要保留足够的确认记录或采用其他可验证机制。
- 消息超时并重新投递后,旧消费者的 ACK 仍可能作用于新的
InFlight 投递。实际实现需要校验本次投递的标识,并检查有效期;续期操作也有同样的问题。
死信队列:重投上限
一条消息反复失败,不能让它无限循环。可以设置投递次数上限,在超时回收时将达到上限的消息转入死信队列:
pub const MAX_DELIVERIES: u32 = 5;
impl Inner {
fn requeue_expired(&mut self) {
let now = std::time::Instant::now();
let expired: Vec<u64> = self
.messages
.values()
.filter(|m| m.state == MsgState::InFlight && m.visible_at <= now)
.map(|m| m.id)
.collect();
for id in expired {
let Some(msg) = self.messages.get_mut(&id) else {
continue;
};
if msg.delivery_count >= MAX_DELIVERIES {
self.dead_letters.push(msg.body.clone());
msg.state = MsgState::Acked;
eprintln!(
"消息 {} 投递 {} 次仍未成功,进入死信队列",
id, msg.delivery_count
);
} else {
msg.state = MsgState::Ready;
msg.consumer = None;
self.ready.push_back(id);
}
}
}
}
这段代码替换前面不带上限的 requeue_expired。它只在超时回收时检查上限;前面的 ack(..., false) 会立即把消息放回就绪队列,因此显式失败路径也需要增加上限检查,才能避免无限重试。
死信队列不仅要有,还必须有人处理。只写不看的死信队列,无法真正完成失败消息的排查和恢复。
生产环境通常还需要:
- 监控告警:例如死信数量大于 0 时告警,具体阈值按业务要求确定。
- 重放工具:修复问题后,将死信重新投递。
- 保留元信息:记录失败原因、投递次数、原队列等信息。
pub struct DeadLetter {
pub body: Vec<u8>,
pub original_id: u64,
pub delivery_count: u32,
pub first_seen: std::time::Instant,
pub last_error: Option<String>,
pub queue: String,
}
last_error 是排查时的重要信息。只有原始消息体,往往无法判断消息为什么失败。上面的 DeadLetter 展示了可以保留的字段,前面的死信代码还需要相应调整,才能实际写入这些信息。
退避:控制重复投递
前面的实现会在消息超时后立即重新放入 ready 队列。如果消费者处理一条消息需要 40 秒,而可见性超时只有 30 秒,就可能发生:
- 30 秒时,消息被重新投递给另一个消费者。
- 两个消费者同时处理同一条消息。
- 后续投递继续超时,产生更多并发处理。
一种缓解思路是随投递次数增加可见性超时:
fn next_visibility_timeout(&self, delivery_count: u32) -> std::time::Duration {
let base = DEFAULT_VISIBILITY_TIMEOUT;
let multiplier = 2u32.saturating_pow(delivery_count.min(5));
(base * multiplier).min(std::time::Duration::from_secs(900))
}
例如,delivery_count 为 3 时,超时为 30 × 8 = 240 秒。更长的处理窗口可以减少因超时设置过短造成的重复投递,但不能保证所有任务都能在期限内完成。
这里增加的是每次投递后的可见性期限,不是失败后等待下一次重投的延迟。若要实现真正的延迟退避,还需要单独安排消息下次可投递的时间。上述函数也需要接入 receive,目前示例仍使用固定的 DEFAULT_VISIBILITY_TIMEOUT。
另一种思路:显式心跳
如果处理时间本来就很长,例如视频转码,更合适的做法是让消费者主动续期:
impl Broker {
/// 消费者处理过程中定期续期
pub fn extend_visibility(
&self,
receipt: &Receipt,
extra: std::time::Duration,
) -> Result<(), BrokerError> {
let mut inner = self.inner.lock().unwrap();
let msg = inner
.messages
.get_mut(&receipt.id)
.ok_or(BrokerError::UnknownMessage)?;
if msg.state != MsgState::InFlight {
return Err(BrokerError::NotInFlight);
}
msg.visible_at = std::time::Instant::now() + extra;
Ok(())
}
}
这一思路对应 SQS 的 ChangeMessageVisibility API。对于处理时间不确定的任务,例如调用外部 API,心跳续期比单纯依赖固定超时更灵活。实际使用时,仍需校验续期请求属于当前有效投递,避免旧消费者延长新一次投递的期限。
拉模型还是推模型
上面的实现采用拉模型:消费者主动调用 receive。
loop {
let Some(receipt) = broker.receive("worker-1") else {
std::thread::sleep(std::time::Duration::from_millis(100));
continue;
};
// 处理
broker.ack(&receipt, true)?;
}
短轮询会反复检查空队列。常见的改进方式有三种。
1. 长轮询(long polling):没有消息时阻塞,直到有消息或等待超时。
pub fn receive_blocking(
&self,
consumer: &str,
timeout: std::time::Duration,
) -> Option<Receipt> {
let deadline = std::time::Instant::now() + timeout;
let mut inner = self.inner.lock().unwrap();
loop {
inner.requeue_expired();
if !inner.ready.is_empty() {
// 有消息,走正常流程
return self.try_receive_locked(&mut inner, consumer);
}
let now = std::time::Instant::now();
if now >= deadline {
return None;
}
let (g, _) = self
.not_empty
.wait_timeout(inner, deadline - now)
.unwrap();
inner = g;
}
}
SQS 和 Kafka 都支持长轮询一类的等待机制。与固定间隔的短轮询相比,它可以在消息到达并触发通知时尽快返回。
示例中的 try_receive_locked 尚未展开,发布消息和失败回队时也需要正确通知等待者。另外,单靠当前等待方式,InFlight 消息超时本身不会触发通知;若希望及时重投,需要结合最近的可见性截止时间唤醒,或使用后台定时任务。
2. 推模型:Broker 主动把消息推给消费者。这要求 Broker 维护消费者连接,并处理消费者反压。
3. 消费者侧批量拉取:一次拉取多条消息,摊薄每次交互的成本。
选择取决于场景:延迟敏感的场景可以考虑长轮询或推模型;吞吐优先的场景可以结合批量拉取。
持久化:Broker 重启不能丢消息
前面的实现都在内存中。要实现持久化,可以引入预写日志 WAL:先记录操作,再更新内存状态。
pub struct PersistentBroker {
broker: Broker,
wal: Wal,
}
impl PersistentBroker {
pub fn publish(&mut self, body: Vec<u8>) -> std::io::Result<u64> {
// 1. 先写 WAL
let id = self.broker.next_id();
self.wal.append(&WalRecord::Publish {
id,
body: body.clone(),
})?;
self.wal.sync()?; // 根据可靠性要求决定是否每条 fsync
// 2. 再进入内存
self.broker.inner.lock().unwrap().enqueue(body);
Ok(id)
}
pub fn ack(&mut self, receipt: &Receipt, success: bool) -> std::io::Result<()> {
self.wal.append(&WalRecord::Ack {
id: receipt.id,
success,
})?;
self.broker.ack(receipt, success).map_err(|e| /* ... */)?;
Ok(())
}
}
这段代码展示写入顺序,Wal、WalRecord、next_id 和错误转换等尚未实现。实际工程还需要保证 WAL 中的 ID 与入队使用的 ID 一致,并根据可靠性要求确定 ACK 日志的刷盘时机。
恢复思路是重放 WAL,重建队列:
pub fn recover(path: &std::path::Path) -> std::io::Result<Self> {
let (wal, records) = Wal::recover(path)?;
let mut broker = Broker::new();
for (_, record) in records {
match record {
WalRecord::Publish { id, body } => {
// 重启后将未确认消息视为 Ready
broker.enqueue_with_id(id, body);
}
WalRecord::Ack { id, .. } => {
broker.mark_acked(id);
}
}
}
Ok(Self { broker, wal })
}
恢复示例同样省略了辅助方法。尤其要注意:这里的 Ack 记录包含 success,但示例恢复代码没有区分成功和失败;实际恢复时必须保留失败消息的可重投状态,不能把所有 ACK 都当作成功确认。投递次数、死信和其他必要状态也需要有对应的持久化与恢复策略。
关键决策是:重启时,将尚未确认的 InFlight 消息视为 Ready。因为消费者可能已经处理完,也可能没有处理完,Broker 无法仅凭内存状态判断。保守地重新投递可能造成重复,但比直接假定处理成功更能避免消息丢失。
这也意味着消费者需要处理重复消息。持久化、恢复和确认流程都满足相应可靠性要求后,才能为至少一次投递提供支撑。
结论
消息队列 Broker 的核心,是把投递语义表达清楚:
使用 Ready、InFlight、Acked 三态区分可取和已确认;通过可见性超时处理消费者崩溃;让 ACK 支持幂等;累计投递次数并在达到上限后转入死信;为重试和长时间处理设计退避或心跳;通过 WAL 支持持久化,并在重启后重新投递未确认消息。
实践中还要明确消息的幂等性:至少一次投递可能带来重复,消费者通常需要通过幂等处理或事务保护业务效果。
因此,讨论 exactly-once 时,必须说明保证的范围。端到端效果不能只靠 Broker 的投递次数判断,还需要结合消费者、存储和事务边界一起设计。