用 Rust 从零实现消息队列:ack、重投和死信才是真正的难点
一个内存队列只要十几行。但把队列做到能上生产的,难度全在"消费者不会恰好正常处理完每一条消息"这个前提上。
消费者可能:处理到一半崩溃、处理失败想重试、处理太慢导致被别人抢走、处理成功但 ack 丢了。broker 的全部复杂度,都是在为这些"不正常"设计语义。
这篇从零实现一个带完整语义的 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 里可能处于三种状态:
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+30s
T+10s A 崩溃了,没人 ack
T+30s broker 检查发现 visible_at 已过,把消息改回 Ready
T+31s 消费者 B 取到这条消息代价是"可能重复投递"——这正是"至少一次"的含义:不丢,但可能重复。
消息队列的语义是一条谱系:at-most-once(可能丢)→ at-least-once(可能重)→ exactly-once(需要幂等或事务)。broker 通常只能提供前两种,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 → 回 Ready),存 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();
// 1. 先把超时的 InFlight 消息放回 ready
inner.requeue_expired();
// 2. 取一条
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,这是"惰性清理"——不需要后台定时器,只要有消费者来取,超时的消息就会被放回来。
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)?;
// 幂等性检查:重复 ack 不应该报错
match msg.state {
MsgState::Acked => return Ok(()), // 已经 ack 过了
MsgState::Ready => return Ok(()), // 已经超时回队了,ack 无效但不算错
MsgState::InFlight => {}
}
if success {
msg.state = MsgState::Acked;
} else {
// 显式失败:立刻重回就绪,不等超时
msg.state = MsgState::Ready;
msg.consumer = None;
inner.ready.push_back(receipt.id);
}
// 清理已 ack 的消息
inner.gc();
Ok(())
}
}"重复 ack 要幂等"这一点非常重要,但经常被忽略。
场景:消费者处理成功 → 发 ack → 网络抖动,ack 没到 → 消费者重试发 ack。如果 broker 第二次 ack 报错,消费者可能会认为"处理失败了",从而重复执行一次业务逻辑。
ack 应该是幂等的,返回成功而不是错误。 这符合"消费者无法区分 ack 丢失和 ack 未到达"这个事实。
死信队列:重投上限
一条消息反复失败,不能让它永远循环。所以要设上限:
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);
}
}
}
}死信队列必须有,且必须有人看。 一个只写不看的死信队列,本质上是"把数据丢了但假装没丢"。
生产上的做法:
- 死信队列要有监控告警(数量 > 0 就告警,而不是"超过 N 条")
- 要有重放工具(修好 bug 之后把死信重新投递)
- 要保留原消息的元信息(失败原因、投递次数、原队列)
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 是排查时的关键信息。 只有原始 body,你根本不知道它为什么失败。
退避:重投不能立即进行
上面的实现里,超时重投是"立即重新进 ready 队列"。这会导致一个严重问题:
消费者处理某条消息需要 40 秒,但可见性超时是 30 秒
→ 30 秒时消息被重投给另一个消费者
→ 两个消费者同时处理同一条消息
→ 又都超时,消息被投给第三个……
→ 消息队列"雪崩":其实只有一个消费者在处理,但有 N 条在飞解法是"重投时把可见性超时拉长"(指数退避):
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))
}重投到第 3 次时,超时变成 30 × 8 = 240 秒。这给了消费者足够的时间处理,避免不必要的重复投递。
另一种思路:显式心跳
如果消息处理时间本来就长(比如转码一个视频),更合理的做法是消费者主动续期:
impl Broker {
/// 消费者处理过程中定期续期,告诉 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 都支持的模式,它把空轮询的延迟从"轮询间隔"降到了"消息到达即返回"。
2. 推模型: broker 主动把消息推给消费者。这需要 broker 维护"消费者连接",并能处理消费者反压。
3. 消费者侧的批量拉取: 一次拉 N 条,摊薄每次交互的成本。
选哪种取决于场景:延迟敏感的用长轮询/推模型;吞吐优先的用批量拉取。
持久化: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,重建 ready 队列和 InFlight 状态。
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(不信任之前的 InFlight 状态)
broker.enqueue_with_id(id, body);
}
WalRecord::Ack { id, .. } => {
broker.mark_acked(id);
}
}
}
Ok(Self { broker, wal })
}关键决策:重启时所有 InFlight 消息都视为 Ready。
为什么?因为消费者状态已经丢了——那些消息可能已经处理完,也可能没处理。保守地重新投递(可能重复)比假设已经处理(可能丢失)更安全,这又是 at-least-once 的体现。
这也意味着消费者必须是幂等的。 无论 broker 设计得多好,"重启后重投"都不可避免。
结论
一个消息队列 broker 的核心,是把"投递语义"表达清楚:
三态消息(Ready / InFlight / Acked)分离"可取"和"已确认";可见性超时处理消费者崩溃;ack 必须幂等;重投计数只增不减,超过上限进死信;重投要退避,长时间处理用显式心跳;持久化靠 WAL,重启时把所有 InFlight 视为 Ready。
最后总结成一条实践原则:
broker 只能保证"至少一次",所以消息的幂等性永远由消费者负责。
理解这一点,你就明白为什么"exactly-once"这个词在消息队列领域总是带着引号——它不是 broker 的单方面承诺,而是"broker 的至少一次 + 消费者的幂等"合作出来的效果。 这也把我们引向下一个话题:当系统里多个副本需要就"谁先谁后"达成一致时,怎么做到不靠中心协调——那就要看 CRDT 了。