Expand description
§wordval-bus
Wordval 事件总线(Bus):以统一 API 封装进程内事件分发与 NATS 扇出,
并可通过 register_backend 接入任意第三方消息中间件(Kafka / Redis / RabbitMQ …),
单机部署零依赖、分布式部署换驱动即可,业务代码不变。
更名说明:本 crate 原名
wordval-queue(历史遗留),2026-09-28 起 更名为wordval-bus——它封装的是发布-订阅事件总线 (at-most-once,见下),并非可靠消息队列——无 ack、无重投、无留存。 需要可靠队列请使用中间件原生能力(如 NATS JetStream consumer)。
§驱动选择
local— 进程内事件分发(默认,零依赖,有界通道)- 每主题单订阅者;无订阅者的事件直接丢弃;
- 处理失败仅记录日志,不重投(at-most-once)。
nats— NATS(需启用natsfeature 且NatsPlugin已启动)- 同主题不同消费组各收一份(扇出),同组内负载均衡。
- 其他 — 由
register_backend注册的自定义后端
§语义契约
- at-most-once:无消费者的事件直接丢弃,处理失败仅记录日志, 不重投、不留存;
- 顺序:
local驱动同一主题内事件按发布顺序严格 FIFO 串行处理 (每主题单任务);NATS 驱动单服务器部署按送达序串行处理,集群部署 无全局顺序保证;跨主题、跨消费组无顺序保证; - handler 约束:处理函数应快速返回——慢 handler 会拖死该主题并使
通道积压(
local触发发布背压 /Bus::try_publish满即拒); 阻塞型工作请用tokio::task::spawn_blocking包装或拆分主题并行消费。
§快速开始
ⓘ
use wordval_bus::{Bus, Message};
let bus = Bus::new("local")?;
bus.subscribe("topic", |msg: Message| async move {
println!("收到事件: {:?}", msg);
Ok(())
}).await?;
bus.publish("topic", b"hello").await?;§插件模式
ⓘ
use wordval_bus::BusPlugin;
use wordval_core::PluginManager;
let mgr = PluginManager::new()
.add(NatsPlugin::new())
.add(BusPlugin::new().with_driver("nats"));
mgr.start_all().await?;
wordval_bus::bus().publish("topic", b"hello").await?;Re-exports§
pub use backend::boxed_handler;pub use backend::register_backend;pub use backend::BusBackend;pub use backend::Handler;
Modules§
- backend
- 总线后端抽象与可插拔注册表
Structs§
- Bus
- 统一事件总线外观:持有一个
BusBackend并暴露高级 API - BusConfig
- 总线配置,驱动名 + 可选参数
- BusPlugin
- 总线插件:管理全局
Bus的生命周期 - Local
Bus - 基于有界 mpsc 通道的进程内事件总线
Constants§
- DEFAULT_
GROUP - 默认消费组名(
BusConfig::default_group与BusPlugin共用)