rust-async-patterns

Rust 异步模式

使用 Tokio 运行时进行异步 Rust 编程的生产级模式，包括任务、通道、流和错误处理。

何时使用本技能

• 构建异步 Rust 应用
• 实现并发网络服务
• 使用 Tokio 进行异步 I/O
• 正确处理异步错误
• 调试异步代码问题
• 优化异步性能

核心概念

1. 异步执行模型

Future (lazy) → poll() → Ready(value) | Pending
                ↑           ↓
              Waker ← Runtime schedules

2. 关键抽象

概念	用途
Future	可能稍后才完成的惰性计算
async fn	返回 impl Future 的函数
await	挂起，直到 future 完成
Task	被派生并并发运行的 future
Runtime	轮询 future 的执行器

快速开始

# Cargo.toml
[dependencies]
tokio = { version = "1", features = ["full"] }
futures = "0.3"
async-trait = "0.1"
anyhow = "1.0"
tracing = "0.1"
tracing-subscriber = "0.3"

use tokio::time::{sleep, Duration};
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize tracing
    tracing_subscriber::fmt::init();

    // Async operations
    let result = fetch_data("https://api.example.com").await?;
    println!("Got: {}", result);

    Ok(())
}

async fn fetch_data(url: &str) -> Result<String> {
    // Simulated async operation
    sleep(Duration::from_millis(100)).await;
    Ok(format!("Data from {}", url))
}

详细模式与完整示例

详细的模式文档位于 references/details.md。当上述导航层级不够用时，请阅读该文件。

最佳实践

应该做的

• 使用 tokio::select! - 用于竞速多个 future
• 优先使用通道 - 尽可能替代共享状态
• 使用 JoinSet - 用于管理多个任务
• 用 tracing 进行插桩 - 用于调试异步代码
• 处理取消 - 检查 CancellationToken

不应该做的

• 不要阻塞 - 绝不要在异步中使用 std::thread::sleep
• 不要在 await 之间持有锁 - 会导致死锁
• 不要无限制地派生任务 - 使用信号量进行限制
• 不要忽略错误 - 用 ? 传播或记录日志
• 不要忘记 Send 约束 - 对于派生的 future