Zerust

Zerust 是一个轻量级的 Rust 网络框架，灵感来源于 Go 语言的 Zinx 框架。它提供了简单易用的 API 和高效的网络通信功能。

特性

• 异步处理：基于 Tokio 异步运行时，提供高性能的并发处理
• 简单接口：简洁明了的 API 设计，易于使用
• 可扩展：灵活的路由系统，支持自定义处理器
• 类型安全：利用 Rust 的类型系统提供编译时安全检查
• 错误处理：完善的错误处理机制和详细的错误信息
• 文档完善：详尽的文档注释，支持 cargo doc 生成完整的 API 文档

安装

在你的项目的 Cargo.toml 文件中添加：

[dependencies]
zerust = "1.0.3"

使用示例

Echo 服务器示例

以下是一个完整的回显服务器示例，包含服务器启动、路由配置、客户端测试和优雅关闭的完整生命周期：

use std::sync::Arc;
use std::time::Duration;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpStream;
use tokio::sync::oneshot;
use zerust::datapack::DataPack;
use zerust::{DefaultRouter, Response, Server};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建关闭通道：用于外部控制服务器生命周期
    let (shutdown_tx, shutdown_rx) = oneshot::channel::<()>();

    // 创建并配置路由器
    let router = Arc::new(DefaultRouter::new());

    // 注册 msg_id = 1 的回显处理函数
    let router_clone = router.clone();
    router_clone.add_route(1, |req| {
        println!("Received echo request: {:?}", req.data());
        Response::new(req.msg_id(), req.data().to_vec()) // 原样返回
    });

    // 启动服务器（异步任务）
    let server = Server::new("127.0.0.1:8000", router);
    let server_handle = tokio::spawn(async move {
        if let Err(e) = server.run(shutdown_rx).await {
            eprintln!("[Zerust] Server runtime error: {}", e);
        }
    });

    // 等待服务器就绪
    tokio::time::sleep(Duration::from_millis(100)).await;
    println!("[Client] Server is ready. Proceeding with test...");

    // 客户端测试
    let mut stream = TcpStream::connect("127.0.0.1:8000").await?;
    println!("Connected to server");

    // 构造请求：msg_id=1, data="test"
    let bytes = DataPack::pack(1, b"test");
    stream.write_all(&bytes).await?;
    println!("Sent request: msg_id=1, data=test");

    // 读取响应头（8字节）
    let mut header = [0u8; 8];
    stream.read_exact(&mut header).await?;
    let (msg_id, data_len) = DataPack::unpack_header(&header)?;
    
    // 读取响应数据
    let mut data = vec![0u8; data_len as usize];
    stream.read_exact(&mut data).await?;
    println!(
        "Received response: msg_id={}, data={:?}",
        msg_id,
        String::from_utf8_lossy(&data)
    );

    // 发送关闭信号
    let _ = shutdown_tx.send(());
    println!("[Main] Shutdown signal sent.");

    // 等待服务器完全停止
    let _ = server_handle.await;

    println!("🎉 Program exited gracefully.");
    Ok(())
}

完整示例代码可在 examples/echo_server_v1.rs 中找到，运行方式：

cargo run --example echo_server_v1

性能测试结果

测试环境

• 操作系统：Windows 10 Pro
• CPU：Intel Core i7-10700 @ 2.90GHz
• 内存：16GB
• 测试工具：自定义基准测试客户端和服务器

Zerust 性能

• 吞吐量：217,391.30 请求/秒
• 平均延迟：92.00 微秒
• 总耗时：0.46 秒
• 完成率：100%

Zinx 性能

• 吞吐量：294,697.33 请求/秒
• 平均延迟：72.89 微秒
• 总耗时：0.34 秒
• 完成率：100%

对比分析

• Zinx 在原始性能上略优于 Zerust
• Zerust 在开发体验和易用性方面更佳
• Zerust 提供了更符合 Rust 生态系统的 API 设计

文档

详细的 API 文档可以通过以下命令生成：

cargo doc --open

也可以参考已发布的文档：https://crates.io/crates/zerust

所有的源代码文件都包含详细的文档注释，包括模块、结构体、方法和函数的说明，以及使用示例。

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🤝 我们遵循 Contributor Covenant 行为准则，欢迎所有贡献者。