返回文章列表

用 Rust 从零实现消息队列:ack、重投和死信才是真正的难点

527 字·5 分钟阅读
Rust从零造轮子消息队列

一个内存队列只要十几行。但把队列做到能上生产的,难度全在"消费者不会恰好正常处理完每一条消息"这个前提上。

消费者可能:处理到一半崩溃、处理失败想重试、处理太慢导致被别人抢走、处理成功但 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 了。