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 读取订单、解码并打印编号。左边手动驱动客户端,右边由运行时驱动。
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,全部再写一遍
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 出发,经过订阅和编解码器到达你的处理器,回复沿原路返回。每个环节都是编译器检查的类型。
- BrokerBroker crate 封装一个客户端,并遵守 conformance 套件检查的契约;核心不依赖任何 Broker。
- 订阅订阅说明要消费什么,在启动时针对已连接的 Broker 解析一次。
- 编解码器编解码器把消息内容转换成处理器的类型:JSON、MessagePack 或 CBOR 在编译时选定,原始字节则完全不需要编解码器。
- 中间件消费层和发布层包裹每一次投递:日志、指标、追踪,或者你自己的层。
- 处理器标注 #[subscriber] 的异步函数;它的返回值决定投递的确认结果,或者成为回复。
- 回复回复类型派生 Outgoing 并声明发往何处;运行时负责编码和发布。
- 发布者发布策略与已连接的 Broker 配对而成;处理器还可以通过有类型的 Out 槽发布。
- AsyncAPI同一组声明生成 AsyncAPI 3.1 文档,因此文档不会与代码脱节。
- 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。基准测试页面列出了全部场景和测量方法,包括会分配内存的路径。
- 宏
- 手写
//! 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))
}
//! The landing-page example written without the `macros` feature: the handler is a named type
//! with an `impl Handle`, mounted with the `subscriber` constructor, and `main` is the one
//! `#[ruststream::app]` would generate.
//!
//! ```text
//! cargo run --example manual_quickstart --no-default-features --features memory,json,logging -- run
//! ```
use ruststream::diagnostics::TracingLogger;
use std::future::ready;
use std::process::ExitCode;
use ruststream::memory::prelude::*;
use ruststream::runtime::cli::run_main;
use serde::Deserialize;
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct Order {
id: u64,
}
/// The handler: `#[subscriber("orders")]` generates this type and this impl. Every axis of the
/// form - the reply, the injections, the broker context, the application state - is a defaulted
/// parameter of `Handle`, so a plain body names none of them.
struct Receive;
impl Handle<Order> for Receive {
fn handle(
&self,
order: &Order,
_outs: &(),
_ctx: &mut Context<'_>,
) -> impl Future<Output = Result<(), HandlerOutcome>> {
tracing::info!(order.id, "got order");
ready(Ok(()))
}
}
fn app() -> RustStream {
RustStream::new(AppInfo::new("orders", "0.1.0"))
.logger(TracingLogger)
.with_broker(MemoryBroker::new(), |b| {
b.include(subscriber("orders", Receive).build())
})
}
fn main() -> ExitCode {
run_main(app)
}
#[ruststream::app] 会生成 main,其中包含运行时的全部样板代码:cargo run -- run 启动服务,cargo run -- asyncapi gen 打印该服务的 AsyncAPI 文档。