跳到主要内容
开源 · Apache-2.0 · 100% 安全 Rust

Rust 异步消息,任意 Broker

#[subscriber] 处理器只写一次,就能运行在 Kafka、NATS、RabbitMQ 以及另外十种 Broker 上;误用在上线之前就由编译器拦下。

一个处理器,十四种传输

Kafkaruststream-rdkafkaNATSruststream-natsRabbitMQruststream-lapinRedis / Valkeyruststream-fredAMQP 1.0ruststream-amqpGoogle Pub/Subruststream-gcp-pubsubSQS / SNSruststream-sqs-snsPulsarruststream-pulsarMQTT 5ruststream-rumqttcZeroMQruststream-zeromqKinesisruststream-kinesis文件 / stdioruststream-sea-fileSQL 数据库ruststream-sqlx进程内存ruststream
同一个消费者,写两遍

写处理器,不写循环

两个程序都从 Kafka 读取订单、解码并打印编号。左边手动驱动客户端,右边由运行时驱动。

src/main.rs · rdkafka手写
use rdkafka::Message;
use rdkafka::config::ClientConfig;
use rdkafka::consumer::{CommitMode, Consumer, StreamConsumer};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Order {
id: u64,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let consumer: StreamConsumer = ClientConfig::new()
.set("bootstrap.servers", "localhost:9092")
.set("group.id", "orders-svc")
.set("enable.auto.commit", "false")
.create()?;
consumer.subscribe(&["orders"])?;

loop {
let msg = tokio::select! {
_ = tokio::signal::ctrl_c() => break,
msg = consumer.recv() => match msg {
Ok(msg) => msg,
Err(err) => {
eprintln!("kafka error: {err}");
continue;
}
},
};
match msg.payload().map(serde_json::from_slice::<Order>) {
Some(Ok(order)) => println!("got order {}", order.id),
Some(Err(err)) => eprintln!("bad payload: {err}"),
None => eprintln!("empty message"),
}
if let Err(err) = consumer.commit_message(&msg, CommitMode::Async) {
eprintln!("commit failed: {err}");
}
}
Ok(())
}
  • 客户端配置和提交方式,全靠手写
  • 解码和每一条错误分支,全靠手写
  • 信号处理和关闭,全靠手写
  • 换一个主题、换一个 Broker,全部再写一遍
src/main.rs · ruststream-rdkafka
use ruststream_rdkafka::prelude::*;
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Order {
id: u64,
}

#[subscriber("orders")]
async fn handle(order: &Order) -> HandlerOutcome {
println!("got order {}", order.id);
HandlerOutcome::ack()
}

#[ruststream::app]
fn app() -> impl App {
RustStream::new(AppInfo::new("orders", "0.1.0")).with_broker(
KafkaBroker::new(["localhost:9092"]).default_group("orders-svc"),
|b| {
b.include(handle);
},
)
}
终端
$ cargo run -- run
04:24:54.781 INFO ruststream::lifecycle starting service service=orders version=0.1.0 brokers=1 subscribers=1
04:24:54.886 INFO ruststream::lifecycle broker connected broker="ruststream_rdkafka::broker::KafkaBroker"
04:24:57.902 INFO ruststream::dispatch subscriber started subscriber=orders input="kafka_quickstart::Order"
04:24:57.902 INFO ruststream::lifecycle service running subscribers=1
# {"id":1} is published to orders
got order 1
04:25:03.779 INFO ruststream::lifecycle shutdown signal received
04:25:03.886 INFO ruststream::lifecycle service stopped

kafka_quickstart 示例在本地 Kafka 上的一次真实运行,开启了 logging feature。

  • 用构建时选定的编解码器解码每条消息
  • 按处理器返回的结果确认每条消息
  • 收到 Ctrl+C 或 SIGTERM 时停止并关闭 Broker
  • 用 asyncapi gen 打印自己的 AsyncAPI 文档,并能在 TestApp 下不依赖 Kafka 运行
架构

一条消息的路径

投递从 Broker 出发,经过订阅和编解码器到达你的处理器,回复沿原路返回。每个环节都是编译器检查的类型。

Broker订阅编解码器中间件处理器回复发布者AsyncAPITestApp
处理器标注 #[subscriber] 的异步函数;它的返回值决定投递的确认结果,或者成为回复。
  1. BrokerBroker crate 封装一个客户端,并遵守 conformance 套件检查的契约;核心不依赖任何 Broker。
  2. 订阅订阅说明要消费什么,在启动时针对已连接的 Broker 解析一次。
  3. 编解码器编解码器把消息内容转换成处理器的类型:JSON、MessagePack 或 CBOR 在编译时选定,原始字节则完全不需要编解码器。
  4. 中间件消费层和发布层包裹每一次投递:日志、指标、追踪,或者你自己的层。
  5. 处理器标注 #[subscriber] 的异步函数;它的返回值决定投递的确认结果,或者成为回复。
  6. 回复回复类型派生 Outgoing 并声明发往何处;运行时负责编码和发布。
  7. 发布者发布策略与已连接的 Broker 配对而成;处理器还可以通过有类型的 Out 槽发布。
  8. AsyncAPI同一组声明生成 AsyncAPI 3.1 文档,因此文档不会与代码脱节。
  9. TestApp测试以进程内的 Broker 启动生产环境的应用,驱动真实的分发流程,不需要服务器。
设计

框架坚持的原则

  • 01

    核心里没有 Broker

    核心只有 trait 和类型。每个 Broker 都是独立的 crate,由 conformance 套件检查是否遵守契约。

  • 02

    Broker 的配置留在 Broker crate 中

    每个 Broker crate 都有自己的 Config。客户端升级只改动这个 crate,框架不受影响。

  • 03

    误用无法通过编译

    ack(self) 会消费这次投递,所以第二次 ack 是编译错误。乱序的生命周期调用同样无法编译。

  • 04

    订阅者就是流

    订阅者是一个 Stream,背压随之而来。运行时在其之上构建处理器。

  • 05

    泛型核心,契约里没有 dyn

    契约建立在关联类型和原生的 async fn in trait 之上。只有服务需要时,运行时才做类型擦除。

  • 06

    能力 trait,而不是臃肿的接口

    批量、事务、请求-回复、分区和重新定位都是独立的 trait。Broker 只实现自己支持的那些。

每条消息的开销

每条消息零次内存分配

框架自身代码在稳定状态下处理一条消息的开销,每次改动都由基准测试计数。Broker 客户端不计入这些数字。

  • 1,697条指令0 次内存分配

    消费一条消息,并把 JSON 解码为结构体

  • 862条指令0 次内存分配

    消费原始字节,不经过编解码器

  • 1,785条指令0 次内存分配

    经过四层中间件消费

  • 2,051条指令0 次内存分配

    编码并发布一条回复

测量环境:ruststream 0.8.0,2026-11-01,AMD Ryzen 9 7900X 12-Core Processor。基准测试页面列出了全部场景和测量方法,包括会分配内存的路径。

从一个处理器开始

用 cargo generate 一分钟生成一个服务,或者向文档提问。

examples/quickstart.rs
//! The landing-page example: a one-handler service with no runtime boilerplate.
//!
//! ```text
//! cargo run --example quickstart --features macros,memory,json,logging -- run
//! ```

use ruststream::diagnostics::TracingLogger;
use ruststream::memory::prelude::*;
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Order {
id: u64,
}

#[subscriber("orders")]
async fn handle(order: &Order) -> HandlerOutcome {
tracing::info!(order.id, "got order");
HandlerOutcome::ack()
}

#[ruststream::app]
fn app() -> RustStream {
RustStream::new(AppInfo::new("orders", "0.1.0"))
.logger(TracingLogger)
.with_broker(MemoryBroker::new(), |b| b.include(handle))
}

#[ruststream::app] 会生成 main,其中包含运行时的全部样板代码:cargo run -- run 启动服务,cargo run -- asyncapi gen 打印该服务的 AsyncAPI 文档。