Smol：Rust 异步运行时的实战指南——从入门到生产部署

houseme
14 Sep, 2025

Photos provided by Unsplash OR Pexels

引言：异步实战的轻量级利器

在 2025 年 9 月的 Rust 生态中，smol 作为一款小巧高效的异步运行时，继续保持其活力。尽管 async-std 已于 2025 年 3 月正式停更，并推荐开发者转向 smol，但 smol 本身在社区中仍活跃，例如在 tor-rtcompat 项目中的集成讨论（2025 年 7 月）。最新版本 2.0.2，由 John Nunley (notgull) 维护，更新于约 2025 年 5 月（基于 crates.io 团队信息，更新于 4 个月前）。smol 的总下载量已超 4742 万，近期下载近 800 万，证明其在轻量级应用中的受欢迎度。

本实战指南聚焦于 smol 的实际应用，结合原理分析、代码示例和生产最佳实践。无论你是构建网络服务、数据管道还是嵌入式系统，本指南将一步步指导你从简单脚本到复杂部署。我们将使用真实场景，强调性能优化和错误处理，确保你的代码高效可靠。准备好，让 smol 驱动你的异步实战！

第一章：环境准备与基础实战

安装与配置

在 Cargo.toml 中添加：

[dependencies]
smol = "2.0.2"  # 最新版本

对于宏支持（如 #[smol::main]），添加：

smol-macros = "0.1"

MSRV 仍为 Rust 1.63，确保兼容 Debian Stable。如果需要与其他运行时兼容，添加 async-compat。

实战 1：简单 HTTP 客户端

场景：从网站获取数据，处理响应。

原理：使用 net::TcpStream 连接，io::copy 传输数据。block_on 驱动单线程执行。

代码：

use smol::{io, net, prelude::*, Unblock};

fn main() -> io::Result<()> {
    smol::block_on(async {
        let mut stream = net::TcpStream::connect("example.com:80").await?;
        let req = b"GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n";
        stream.write_all(req).await?;

        let mut stdout = Unblock::new(std::io::stdout());
        io::copy(&mut stream, &mut stdout).await?;
        Ok(())
    })
}

运行：cargo run，输出网页内容。优化：使用 Unblock 避免阻塞 executor。

第二章：并发与多线程实战

实战 2：并发文件处理管道

场景：批量读取文件，处理数据，支持并发限流。

原理：fs::read 使用 async-fs，非阻塞 I/O。Semaphore 控制并发，channel 传递结果。

代码：

use smol::{channel, fs, lock::Semaphore, prelude::*};
use std::sync::Arc;

#[smol::main]
async fn main() -> std::io::Result<()> {
    let sem = Arc::new(Semaphore::new(5));  // 限流 5
    let (tx, rx) = channel::unbounded::<Vec<u8>>();

    for i in 0..10 {
        let sem = sem.clone();
        let tx = tx.clone();
        smol::spawn(async move {
            let _guard = sem.acquire().await;
            let data = fs::read(format!("file{}.txt", i)).await.unwrap();
            tx.send(data).await.unwrap();
        }).detach();
    }

    drop(tx);  // 关闭发送端
    while let Ok(data) = rx.recv().await {
        println!("Processed {} bytes", data.len());
    }
    Ok(())
}

分析：通道确保顺序处理。适用于 ETL 管道。

实战 3：多线程网络服务器

场景：构建 TCP 服务器，支持多线程处理连接。

原理：Executor<‘static> 启用工作窃取。多线程通过 thread::spawn 运行 tick()。

代码：

use smol::{io, net::TcpListener, prelude::*, Executor};
use std::sync::Arc;
use std::thread;
use std::num::NonZeroUsize;

fn main() -> io::Result<()> {
    let ex = Arc::new(Executor::new());
    let thread_count = num_cpus::get();

    let handles: Vec<_> = (0..thread_count).map(|_| {
        let ex = ex.clone();
        thread::spawn(move || loop { let _ = ex.tick(); })
    }).collect();

    smol::block_on(ex.run(async {
        let listener = TcpListener::bind("0.0.0.0:8080").await?;
        loop {
            let (stream, _) = listener.accept().await?;
            ex.spawn(handle_connection(stream)).detach();
        }
    }))?;

    for handle in handles {
        handle.join().unwrap();
    }
    Ok(())
}

async fn handle_connection(mut stream: smol::net::TcpStream) {
    let mut buf = [0; 1024];
    while let Ok(n) = stream.read(&mut buf).await {
        if n == 0 { break; }
        stream.write_all(&buf[..n]).await.unwrap();
    }
}

优化：添加 num_cpus 依赖。适用于 echo 服务器。

第三章：集成与高级功能实战

实战 4：与第三方库集成（apalis 示例）

场景：使用 smol 作为 apalis（任务队列）的运行时。自 2025 年，apalis 支持 smol 无缝集成。

首先添加 apalis = "0.5"（假设版本）。

代码：

use apalis::prelude::*;
use smol::Executor;

async fn process_task(data: String) -> Result<(), anyhow::Error> {
    println!("Processing: {}", data);
    Ok(())
}

#[smol::main]
async fn main() -> anyhow::Result<()> {
    let ex = Executor::new();
    let worker = WorkerBuilder::new("my-queue")
        .with_executor(ex)
        .build_fn(process_task);

    // 假设 Redis 存储
    worker.run().await?;
    Ok(())
}

分析：apalis 适应 smol，提供分布式任务。

实战 5：定时任务与进程管理

场景：定时执行 shell 命令，处理输出。

原理：Timer 发出事件，process::Command 异步运行。

代码：

use smol::{process, Timer};
use std::time::Duration;

#[smol::main]
async fn main() -> std::io::Result<()> {
    loop {
        Timer::after(Duration::from_secs(60)).await;
        let output = process::Command::new("ls").output().await?;
        println!("Output: {}", String::from_utf8_lossy(&output.stdout));
    }
}

第四章：生产部署最佳实践

性能监控：使用 tracing crate，RUST_LOG=debug 追踪 poll。基准测试显示 smol 在小负载下高效。
错误处理：集成 anyhow；使用 Task::cancel() 管理取消。
部署：Dockerize 应用，设置线程池大小：blocking::set_threadpool_size(NonZeroUsize::new(128).unwrap())。
迁移 async-std：直接替换运行时，测试兼容。
安全：使用 lock 原语避免 race；TLS 示例见仓库。
测试：使用 #[smol::test] 宏异步测试。
局限：高并发时考虑 tokio；smol 适合 <1000 连接。