socket_io_client
socket_io_client 是一个用 Rust 编写的简易 Socket.IO 客户端库。
⚠️ 兼容性提示: 本客户端目前主要针对 socketioxide 服务端进行适配与测试,致力于在 Rust 生态中提供首尾一致的、符合人体工程学的开发体验。它支持通过 ClientApp 管理全局状态,能够方便地注册不同命名空间(Namespace),并采用了基于 Extractor(提取器)机制的事件路由注册方法,让事件处理函数的签名更加灵活清晰。
✨ 核心特性
- 全局状态与命名空间管理:通过
ClientApp 轻松管理客户端全局状态,并支持多命名空间(如 /、/admin)的独立事件注册。
- Axum 风格的 Extractor(提取器):事件回调函数支持灵活的参数提取,例如
CSocket<State>、CData<Value>、CState<State> 和 Ack,无需手动解析上下文。
- 完善的事件收发机制:
- 支持
on_connect、on_disconnect 监听连接生命周期。
- 支持
on 监听自定义事件。
- 支持
emit、emit_args 发送 JSON 或多参数事件。
- 支持带确认机制的
emit_with_ack。
- 大文件/二进制数据分片上传(防断线背压):支持
emit_binary_with_ack,结合 Ack 机制实现天然背压,可防止在发送大体积二进制文件(如 Zip 压缩包)时阻塞 Ping/Pong 心跳导致断线。
- 定时任务集成:提供
socket.run_interval 轻松注册与 Socket 生命周期绑定的定时循环任务。
- 自动重连:可自定义重连间隔(
set_reconnect_interval)与超时时间(set_pong_timeout)。
🚀 快速开始
1. 添加依赖
在 Cargo.toml 中添加:
[dependencies]
socket_io_client = "0.1.0"
serde_json = "1.0"
tokio = { version = "1.0", features = ["full"] }
tracing = "0.1"
2. 编写客户端代码
use serde_json::{json, Value};
use socket_io_client::{ClientApp, ClientSocketRef, Data as CData, Socket as CSocket, State as CState};
use std::sync::Arc;
use tokio::sync::Mutex;
use tracing::info;
#[derive(Clone)]
pub struct AppState {
pub message_count: Arc<Mutex<usize>>,
}
#[tokio::main]
async fn main() {
tracing_subscriber::fmt::init();
let state = AppState {
message_count: Arc::new(Mutex::new(0)),
};
let mut app = ClientApp::new(state);
app.set_reconnect_interval(3);
app.set_pong_timeout(8);
app.ns("/", |socket: ClientSocketRef<AppState>| async move {
socket.on_connect::<CSocket<AppState>, CState<AppState>, _, _>(
|CSocket(s), CState(_)| async move {
info!("连接成功!");
let _ = s.emit("hello_server", json!({"msg": "hello from client"})).await;
}
);
socket.on_disconnect::<CSocket<AppState>, CState<AppState>, _, _>(
|CSocket(_), CState(_)| async move {
info!("连接断开!");
}
);
socket.on::<CSocket<AppState>, CData<Value>, CState<AppState>, _, _>(
"server_msg",
|CSocket(s), CData(data), CState(state)| async move {
info!("收到服务器消息: {:?}", data);
let mut count = state.message_count.lock().await;
*count += 1;
info!("总共收到 {} 条消息", *count);
let _ = s.emit("client_reply", json!({"reply": "got it"})).await;
}
);
});
app.run("http://127.0.0.1:3000").await;
}
💡 进阶功能示例
发送带 Ack 的请求
use std::time::Duration;
socket.on::<CSocket<AppState>, CData<Value>, CState<AppState>, _, _>(
"get_user_info",
|CSocket(s), CData(data), CState(_)| async move {
match s.emit_with_ack("get_user", json!(123), Duration::from_secs(3)).await {
Ok(res) => info!("成功收到服务端的 ACK 响应: {}", res),
Err(e) => info!("等待服务端 ACK 超时或失败: {:?}", e),
}
}
);
二进制大文件分片上传
为了避免大量发送二进制数据阻塞心跳导致断线,推荐使用分片和 Ack 机制进行自然背压:
let chunk = vec![0u8; 256 * 1024]; let chunk_meta = json!({ "file_name": "test.zip", "chunk_index": 0 });
if let Err(e) = s.emit_binary_with_ack(
"upload_zip_chunk",
vec![chunk_meta],
vec![chunk], Duration::from_secs(5),
).await {
tracing::warn!("分片上传失败: {}", e);
}
提示:在服务端(如 socketioxide 0.18.x)可通过 Data::<(Value, bytes::Bytes)> 提取器同时接收 JSON 元数据与二进制块。
🧪 运行示例项目 (Examples)
本项目在 examples 目录下提供了完整的客户端和服务端联调示例。
examples/server_test: 基于 Leptos 和 socketioxide 搭建的测试服务端。
examples/client_test: 基于本库搭建的测试客户端。
启动联调测试步骤:
- 进入服务端目录并启动服务端:
cd examples/server_test
cargo leptos watch
- 等待服务端启动完成(约 3 秒)。
- 新开一个终端,进入客户端目录并启动客户端:
cd examples/client_test
cargo run
🔗 参照项目
本项目的实现和 API 设计主要参考了官方 Socket.IO 客户端和 Rust 生态优秀的库:
📄 许可证
本项目基于 MIT 许可证开源。详细信息请参阅 LICENSE 文件。