Rust on 小类随手记

Rust 双模式实时交互：一套事件总线同时服务 Web 与 Tauri

Fri, 31 Jul 2026 13:37:41 +0800

本文记录一种 Rust 应用的实时数据交互设计：一个 Rust 后端同时服务两种前端形态（浏览器 Web 客户端与 Tauri 桌面客户端 WebView）时，如何用"传输无关的事件总线 + 两端薄适配 + 前端统一订阅抽象"实现实时数据推送，避免为两种传输各写一套逻辑。

背景与挑战

一个 Rust 应用常常有两种形态：Web 版（Rust 起 HTTP 服务，浏览器访问）和桌面版（Tauri 壳 + 内置 WebView）。业务逻辑在核心层共享，但前后端通信通道完全不同：

Web 模式：浏览器只能走 HTTP，实时推送用 SSE 或 WebSocket
Tauri 模式：前端运行在 Rust 进程内的 WebView 里，可以直接走 Tauri 的原生事件通道（emit/listen），绕开 HTTP

如果为两种模式分别实现实时交互，会产生两个问题：

业务代码里混入传输细节，核心层被 axum::Sse 或 tauri::Emitter 污染
前端要维护两套订阅逻辑，行为不一致（比如鉴权、重连策略不同）

目标设计：核心层只发布领域事件，不感知传输；服务壳与 Tauri 壳各做一个薄适配层；前端提供与 API 调用对称的统一订阅抽象。

总体架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


写操作（核心层业务逻辑）
 │ 发布
 ▼
┌──────────────────────┐
│ EventBus（事件总线） │ 传输无关，基于 tokio::sync::broadcast
└───────┬──────────────┘
 │ 订阅
 ┌────┴─────┐
 ▼ ▼
服务壳(SSE) Tauri壳(原生Event)
GET /api/events app.emit("app://event")
 │ │
 ▼ ▼
浏览器 fetch 流 WebView listen
 └──────┬───────┘
 ▼
前端统一 event-client（按运行环境分流）
 │
 TanStack Query invalidate / 状态 store

核心思路：核心层发布事件时不知道事件会以什么方式到达前端；传输适配只在两个壳里完成；前端用一个客户端抽象屏蔽差异。

事件总线设计

事件总线放在核心层，与业务逻辑同进程，基于 tokio::sync::broadcast：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


pub struct Event {
 pub topic: &'static str, // 事件主题，如 "task.progress"
 pub seq: u64, // 单调递增序号，用于断线补漏
 pub payload: serde_json::Value,
}

pub struct EventBus {
 tx: broadcast::Sender<Event>,
}

impl EventBus {
 pub fn publish(&self, topic: &'static str, payload: serde_json::Value) {
 let seq = self.next_seq();
 let _ = self.tx.send(Event { topic, seq, payload });
 }

 pub fn subscribe(&self) -> broadcast::Receiver<Event> {
 self.tx.subscribe()
 }
}

选择 broadcast 而不是 mpsc 的原因：

天然支持多订阅者：多个浏览器 Tab、多个设备、Tauri 转发器可以同时订阅同一份事件流
慢订阅者自动落后，配合 lagged 计数可以检测断线期间丢了多少事件
容量按最坏情况配置（如 1024），事件发布是内存操作，成本极低

事件主题统一为 &'static str 常量，payload 一律 serde_json::Value。这样无论走 SSE 还是 Tauri 原生通道，payload 都是同一个结构，序列化零转换。

发布侧：谁写谁发布

实时交互的关键约定：所有写路径必须收敛到核心层的方法上，在成功完成后发布对应主题的事件。如果写路径分散在壳层，就会漏发事件导致各端状态不一致。

两个典型场景：

长任务进度：worker 循环里拿到进度后发布 task.progress，但要节流（如每 500ms 一条），避免高频事件压垮订阅者和前端；终态（完成/失败/取消）立即发布不节流
配置变更：增删改配置成功后发布 config.changed，前端收到后使相关查询失效，重新拉取

节流放哪一层？放在发布侧（核心层）而不是消费侧，因为一个发布者可能对应多个订阅者，源头节流才能保证总流量可控。payload 保持小体积，只带最小必要字段。

服务壳：SSE 适配

Web 模式用 SSE（Server-Sent Events）而不是 WebSocket：

SSE 基于普通 HTTP，天然支持鉴权头、自动重连、与现有 REST 体系共用中间件
单向推送足够（前端不需要通过事件通道回传数据，回传走普通 API）
axum 有现成的 Sse + KeepAlive 支持

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


pub async fn events_subscribe(
 State(app): State<AppContext>,
 Query(params): Query<AuthParams>, // ?token= 鉴权
) -> Sse<impl Stream<Item = Result<Event, Infallible>>> {
 // 1. 手动校验 JWT（EventSource / fetch 无法自定义 Authorization 头时的备选）
 // 2. 从 EventBus 订阅一个 receiver
 let rx = app.events.subscribe();
 let stream = BroadcastStream::new(rx).map(|item| {
 let event = item.unwrap_or_else(|lagged| /* 断线补偿事件 */);
 Ok(Event::json(event))
 });
 Sse::new(stream).keep_alive(KeepAlive::new().interval(Duration::from_secs(15)))
}

设计要点：

每个连接一个 broadcast 订阅者，连接断开时 receiver 自动丢弃，不泄漏
15s KeepAlive ping 保持代理/负载均衡器不断连，也用于检测死连接
SSE 事件名直接用 topic，前端 addEventListener(topic) 按主题分发
鉴权不走全局中间件，路由挂在受保护路由组之外，handler 内自校验，支持 ?token= 查询参数——因为浏览器 EventSource 无法自定义请求头

Tauri 壳：原生事件适配

Tauri 模式没有 HTTP，前端 WebView 与 Rust 进程通过原生事件通道通信。适配层只是一个转发器：订阅 EventBus，把每个事件 app.emit 出去。

1
2
3
4
5
6
7
8


// setup 中 spawn 一个转发任务
let bus = app.state::<AppContext>().events.clone();
tauri::async_runtime::spawn(async move {
 let mut rx = bus.subscribe();
 while let Ok(event) = rx.recv().await {
 let _ = app.emit("app://event", &event);
 }
});

要点：

payload 是 serde_json::Value，Serialize + Clone 天然满足，直接传引用即可
桌面模式是单进程内通信，无需鉴权、无需重连、无需 KeepAlive，比 SSE 简单一个数量级
事件通道名固定一个（如 app://event），内部再按 topic 分发，与 SSE 的"事件名 = topic"在语义上对齐

前端统一订阅抽象

前端与 api-client 对称，提供一个 event-client 单例：启动时检测运行环境（浏览器 fetch 还是 Tauri invoke），选择对应实现，向上暴露同一套 API：

1
2
3
4
5


type EventHandler = (payload: unknown) => void;

// 统一接口
subscribe(topic: string, handler: EventHandler): Unsubscribe;
onStatus(cb: (connected: boolean) => void): void;

Web 模式：fetch + ReadableStream 解析 SSE

浏览器原生 EventSource 有两个硬伤：无法自定义 Authorization 头（只能 ?token=，token 会进日志），且无法精细控制重连。所以用 fetch + ReadableStream 手动解析 SSE 帧：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


async function connectSSE(token: string) {
 const res = await fetch('/api/events', {
 headers: { Authorization: `Bearer ${token}` },
 });
 const reader = res.body!.getReader();
 const decoder = new TextDecoder();
 let buffer = '';
 while (true) {
 const { done, value } = await reader.read();
 if (done) break;
 buffer += decoder.decode(value, { stream: true });
 // 按空行切分 SSE 帧，解析 event: / data: 字段
 // 按 topic 分发到 handler
 }
}

Tauri 模式：原生 listen

动态 import @tauri-apps/api/event，避免 Web 包打进多余的 Tauri 依赖：

1
2
3
4
5
6
7


async function connectTauri() {
 const { listen } = await import('@tauri-apps/api/event');
 await listen('app://event', (e) => {
 const event = e.payload as { topic: string; payload: unknown };
 dispatch(event.topic, event.payload);
 });
}

统一的重连与状态管理

连接状态（connected/disconnected）通过 onStatus 通知 hooks
Web 模式断线后指数退避重连（1s → 2s → 4s → 上限），401 时先刷新 token 再重连
Tauri 模式进程内通道几乎不会断，但代码路径保持同一套接口

消费侧：事件驱动的查询失效与状态合并

前端拿到事件后怎么用，分两种场景：

查询失效（配置类事件）

配置变更事件不携带完整数据，只带变更动作。前端收到后让相关 TanStack Query 失效（invalidate），下次读取自动重新拉取。这样事件通道只负责"通知变了"，数据一致性仍由查询层保证，不用在事件里塞大 payload。

1
2
3
4


// 全局订阅，收到配置变更就失效对应查询
subscribe('config.changed', () => {
 queryClient.invalidateQueries({ queryKey: ['config'] });
});

状态合并（进度类事件）

高频进度事件不适合进查询层（会触发整页 re-render），用 Zustand store 单独管理：

1
2
3
4


// 进度 store：task_id -> 最新进度 payload
subscribe('task.progress', (p) => {
 useProgressStore.setState((s) => ({ [p.taskId]: p.payload }));
});

UI 渲染时把查询数据（任务的静态信息）与 store 数据（实时进度）合并。终态事件到达时清掉 store 对应条目并失效查询，恢复为查询层的数据源。

轮询降级

订阅可用时停掉轮询，断开时自动恢复轮询兜底：

1

refetchInterval: connected ? false : 3000,

这条规则保证：实时通道正常时零轮询、零延迟；断线期间退化到轮询，数据不中断；重连成功后自动切回事件模式。

可靠性设计

断线补漏：事件带 seq 单调递增，订阅者可以检测丢失。落地时先做"连接建立即快照补齐"——重连成功后把相关查询全部 invalidate 一遍，用一次全量拉取弥补断线窗口丢失的事件；seq 留作后续精确补漏
事件丢失兜底：broadcast 满容量时慢订阅者会 lagged，转发器要处理 RecvError::Lagged，把 lagged 计数当作一次补偿信号（触发快照补齐）
高频事件节流在发布侧，保证多订阅者场景下总量可控
长连接与普通 API 的超时策略分开：SSE 连接不能套用 API 的 30s 超时，前端要为事件通道单独实现

总结

这套设计最终形成三个对称：

核心层不感知传输，发布侧与传输侧解耦
服务壳与 Tauri 壳各只做 50 行左右的适配代码，没有业务逻辑
前端 api-client（请求）与 event-client（订阅）对称，按运行环境分流

对于"同一个 Rust 核心要同时喂浏览器和桌面端"的应用，这是成本最低、行为最一致的实时交互方案。事件总线、SSE、Tauri 原生事件三者各司其职，前端永远只面对一个订阅接口。

redis走websocket的方法：另一种实时通道设计——用 WebSocket 反向代理暴露命令接口，与本文 SSE 推送方案可对照传输方式取舍
Nginx Proxy Manager 或者其他nginx包括宝塔ssl嵌套coderserver都1006错误：WebSocket 长连接经反代部署时的 1006 错误与代理配置，对应本文 SSE 的 KeepAlive 保活设计

在 Rust 中运行js，用QuickJS+ JavaScript 打造插件引擎

Fri, 31 Jul 2026 13:30:22 +0800

本文记录在 Rust 应用中嵌入 QuickJS（通过 rquickjs 绑定）实现 JS 插件引擎的完整技术方案与思路，包括异步运行时、宿主与脚本的双向桥接、CommonJS 兼容层、原生能力注入、线程模型与编码处理等关键设计。

为什么用 JS 做插件语言

一个长期维护的 Rust 应用，业务能力需要持续扩展，但不可能每个新能力都改 Rust 源码重新编译。插件化的常见方案有：

动态库（cdylib）：性能好，但 ABI 不稳定、跨平台编译麻烦、版本兼容噩梦
WASM：生态成熟，但插件作者需要懂 Rust/Go 等语言，学习曲线陡
内嵌脚本引擎（Lua/JS/Python）：插件只是一份文本文件，改完即生效，无需编译

选择 JavaScript 的理由很直接：

语法亲和，前端开发者零成本上手
JSON 原生支持，与 HTTP API 数据天然契合
社区有大量现成插件生态可参考，比如各大音乐聚合类应用的插件都是 JS 写的，接口约定成熟
不需要打包分发，插件就是一个 .js 文件

脚本引擎里 QuickJS 是体积与性能平衡最好的选择：单个二进制几百 KB，无 JIT（天然规避了 iOS 审核等场景对 JIT 的限制），内存占用低，适合作为嵌入式运行时。

技术选型：rquickjs

Rust 侧绑定选 rquickjs，相比 other 的绑定库：

对 QuickJS 的封装完整，支持运行时快照、模块加载
原生支持 async/await（AsyncRuntime / AsyncContext），这是关键
提供 bindgen 宏（声明式导出 Rust 函数给 JS）与 futures feature（Promise 与 Rust Future 互转）

Cargo 依赖：

1
2


rquickjs = { version = "0.12.1", features = ["bindgen", "futures"] }
rquickjs-serde = "0.6.1"

架构总览

整体分三层：

宿主侧（Rust）：定义插件接口 trait，管理插件生命周期，调用脚本
桥接层（IIFE 模板 + 注入的原生函数）：负责 JS 与 Rust 的互操作
脚本侧（JS）：插件本体 + 内置 polyfill 包（sandbox.js）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


┌─────────────────────────────────────────┐
│ Rust 宿主 │
│ ┌───────────┐ ┌──────────────────┐ │
│ │ trait API │ │ AsyncRuntime │ │
│ │ (业务接口) │ │ AsyncContext │ │
│ └─────┬─────┘ └────────┬─────────┘ │
└────────┼──────────────────┼─────────────┘
 │ eval IIFE │ Function::new(Async(fn))
 ▼ ▼
┌─────────────────────────────────────────┐
│ QuickJS 运行时 │
│ ┌───────────────────────────────────┐ │
│ │ sandbox.js (axios/cheerio/qs...) │ │
│ │ 插件代码 (module.exports) │ │
│ └───────────────────────────────────┘ │
└─────────────────────────────────────────┘

宿主调用协议：IIFE 模板

QuickJS 的 Ctx::eval 直接执行一段代码字符串。插件加载与调用都通过预定义的 IIFE 模板完成，把插件源码内联进模板再 eval。

加载插件时只读取元数据（平台名、版本、作者、支持的方法列表），不执行任何业务逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


(function() {
 var module = { exports: {} };
 var exports = module.exports;
 var require = function(n) {
 var p = __musicfree_packages[n];
 if (!p) throw Error('no module: ' + n);
 p.default = p;
 return p;
 };
 var __load_err = null;
 try { /* 插件源码内联在此 */ } catch(e) { __load_err = String(e); }
 var inst = module.exports.default || module.exports;
 var names = Object.keys(inst).filter(function(k) { return typeof inst[k] === 'function'; });
 return JSON.stringify({ p: inst.platform, v: inst.version, a: inst.author, m: names, e: __load_err });
})();

调用具体方法时使用 async IIFE，支持插件内部 await 网络请求：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


(async function() {
 var module = { exports: {} };
 /* ... 同上 require 兼容 ... */
 try { /* 插件源码内联在此 */ } catch(e) { return JSON.stringify({'__plugin_load_error': String(e)}); }
 var inst = module.exports.default || module.exports;
 var fn = inst['__FN__'];
 var a = JSON.parse('__ARGS__');
 try {
 var r = await fn.apply(null, a);
 return JSON.stringify(r);
 } catch(e) {
 return JSON.stringify({'__plugin_error': String(e) + ' | ' + (e.stack || '')});
 }
})();

这个设计的要点：

插件源码每次调用都会重新内联执行，因此天然无状态、无残留全局变量，不需要复杂的沙箱隔离
CommonJS 兼容：手工模拟 module.exports / exports / require，插件按 CommonJS 风格编写即可
返回值统一走 JSON 字符串，Rust 侧反序列化，边界干净
插件抛错被捕获后包装成 __plugin_error 字段，宿主侧统一转成错误枚举，不 panic

异步桥接：两个方向的 Promise

QuickJS 本身是同步引擎，rquickjs 的 futures feature 把 JS Promise 和 Rust Future 打通，这是整个引擎能支持 async/await 的基础。

Rust 原生函数注入 JS（Rust → JS）

用 Function::new 包一个 async 函数，注册到全局对象上。JS 侧调用它得到的是一个真正的 Promise：

1
2
3
4
5
6
7
8
9


use rquickjs::prelude::Async;

// 原生 HTTP 函数：接收 JSON 字符串配置，返回 JSON 字符串
async fn native_http_js(config: String) -> String {
 // ... reqwest 发请求，返回 {"status":..,"headers":..,"data":..}
}

let f = Function::new(ctx.clone(), Async(native_http_js))?;
ctx.globals().set("__native_http_async", f)?;

MD5、SHA256、HMAC、Base64 等同步函数同样注入，但不需要 Async 包装：

1
2
3
4


let f = Function::new(ctx.clone(), |s: String| -> String {
 hex::encode(Md5::digest(s.as_bytes()))
})?;
ctx.globals().set("__native_md5", f)?;

JS Promise 返回值取回（JS → Rust）

ctx.eval 返回的 Promise 通过 into_future 转成 Rust Future 直接 await：

1
2


let promise: Promise<'_> = ctx.eval(&*code)?;
let result_json: String = promise.into_future::<String>().await?;

这样插件内部可以自由地 await axios.get(...)、Promise.all([...]) 并发请求，宿主完全感知不到区别。

为什么用 JSON 字符串做参数边界

跨语言传参有两条路：直接传 JS 值（JsValue）或序列化成 JSON 字符串。项目选择了后者：

参数/返回值全部 serde_json::Value 序列化，类型边界简单，宿主侧代码不用碰 JsValue 的借用来
插件数据天然是 JSON（网络接口返回的就是 JSON），零转换成本
出错时能拿到完整的字符串便于日志

线程模型：非 Send 的 QuickJS 与 tokio

QuickJS 运行时不是 Send，无法直接跨 tokio 任务移动。rquickjs 的 AsyncRuntime 内部用独立线程跑事件循环解决了一部分问题，但 Ctx 仍然不能跨线程。实际采用的模式是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


tokio::task::spawn_blocking(move || {
 // QuickJS 非 Send，必须独占线程
 let local_rt = tokio::runtime::Runtime::new()?;
 local_rt.block_on(async {
 let rt = AsyncRuntime::new()?;
 let ctx = AsyncContext::full(&rt).await?;
 ctx.async_with(async |ctx| {
 // 注册原生函数、eval IIFE、await Promise
 }).await
 })
}).await?

要点：

spawn_blocking 保证 QuickJS 每次调用独占一个线程，闭包捕获的数据要求 Send + 'static
闭包内部再建一个本地 tokio runtime，block_on 驱动 async 上下文，这样 promise.into_future().await 才能跑起来
每次调用都是新建 runtime + context，用完即弃。对低频插件调用（一次搜索/一次详情请求）完全够用，还顺带获得了天然隔离——插件状态不会泄漏到下一次调用
代价是每次调用都有上下文创建开销，不适合高频短调用场景。如果业务需要，可以改为线程池 + 常驻 context

沙箱与兼容层：一个文件内嵌的 npm 生态

插件生态里大量使用 axios、cheerio、crypto-js、qs、he、dayjs 这些包。QuickJS 没有 npm，方案是在 sandbox.js 里用原生 JS 手写这些包的迷你实现，注册到 require 能查到的包表里：

1
2
3
4
5


// sandbox.js 片段
__musicfree_packages['axios'] = axios;
__musicfree_packages['cheerio'] = cheerio;
__musicfree_packages['crypto-js'] = cryptoJs;
__musicfree_packages['qs'] = qs;

axios：完整实现 get/post/request/create、params 拼接、POST JSON 自动加 Content-Type、错误响应包装，底层转发到 __native_http_async
cheerio：正则实现的轻量 HTML 解析，支持选择器、find/text/attr/children 等常用方法
crypto-js：MD5/SHA256/HmacSHA256/Base64 直接转发 Rust 原生函数（__native_md5 等），AES 预留了原生转发位
qs / he / dayjs：纯 JS 迷你实现

关键收益：插件作者按熟悉的 API 写代码，宿主侧用原生实现兜底性能敏感的加密哈希，两全其美。

编码处理：从 BOM 到 GBK 乱码

网络数据编码问题在中国区 API 上非常普遍，做了三层防御：

剥离 UTF-8 BOM：响应体前 3 字节是 EF BB BF 时去掉
UTF-8 解码失败回退 GBK：encoding_rs::GBK 兜底，覆盖大量老接口
歌词乱码修复：如果文本中 Latin-1 区字符（0x80-0xFF）占比超过阈值，说明是 GBK 字节被按 Latin-1 误读了，重新按 GBK 解码

1
2
3
4
5
6


fn decode_body(bytes: &[u8]) -> String {
 let bytes = strip_bom(bytes);
 if let Ok(s) = std::str::from_utf8(bytes) { return s.to_string(); }
 let (cow, _, _) = encoding_rs::GBK.decode(bytes);
 cow.to_string()
}

踩坑记录

AsyncRuntime 不等于无脑跨线程：Ctx 依旧借用运行时，必须小心作用域，async_with 闭包内完成所有操作再返回
Function::new 的 async 闭包要求 Send + 'static，捕获的 reqwest client 要用 OnceLock 静态化，避免每次调用重建连接池
插件里 Object.assign、encodeURIComponent 在 QuickJS 中可能缺失，sandbox.js 里补了 polyfill
eval 大字符串（插件源码几十 KB）性能可以接受，但注意 replace("__JS_CODE__", js) 时如果插件源码本身含有模板占位符字符串会误替换，占位符要选足够独特的名字
每次调用新建 context 的隔离方案意味着插件不能用全局变量跨调用缓存 token，需要插件侧自己把状态放进返回数据里（业务上一般也足够）

总结

整套方案的最终形态：

插件 = 一个 JS 文件，按 CommonJS 风格写 module.exports，实现约定好的方法名即可
宿主侧用 trait 抽象插件能力，JS 引擎只作为其中一个实现
双向异步桥接靠 rquickjs 的 futures feature，参数边界统一 JSON 字符串
隔离靠"每次调用新建 context"而非沙箱，简单且可靠
生态兼容靠 sandbox.js 手写迷你包 + 原生函数转发

对于"Rust 应用需要快速扩展能力、又不想频繁发版"的场景，这套 QuickJS 插件方案值得参考。