rust-async-task-design

Rust 异步任务设计

使用此技能，让 Rust 异步代码明确任务所有权、挂起点、阻塞工作和取消行为。异步是一种并发模型，并非线程的默认替代方案，也不保证性能。

核心工作流

1. 确定异步边界：运行时入口点、处理程序、客户端调用、流、后台任务或 trait 方法。
2. 将每个 .await 标记为可能的挂起点。检查有哪些状态会跨越该挂起点。
3. 仅当任务能够拥有所需的一切，且其 future 在所选运行时上满足 Send + 'static 时，才使用 tokio::spawn(async move { ... })。
4. 如果任务的成功、panic、取消或关闭情况很重要，就保留 JoinHandle。不要默默分离重要工作。
5. 不要在异步任务中执行阻塞 IO 和 CPU 密集型工作。根据工作负载使用异步 API、spawn_blocking、Rayon 或专用线程。
6. 不要让同步 MutexGuard、RefCell 借用或非 Send 值跨越 .await。
7. 如果超时、取消、通道关闭和任务失败会影响行为，就为这些情况添加测试。

运行时规则

审核任务生成、异步代码中的共享状态或阻塞工作时，请阅读 references/async-runtime-patterns.md。

• 仅当临界区较短、竞争较少且不会跨越 .await 时，才在异步代码中使用 std::sync::Mutex。
• 如果锁必须跨越 .await，则使用 tokio::sync::Mutex，但应先考虑将状态放到一个任务中，并通过消息与其交互。
• 对最终会完成的阻塞操作使用 spawn_blocking。限制 CPU 密集型工作的并行度；Tokio 的阻塞线程池可能会扩展得很大。
• 对有界操作使用 tokio::time::timeout 或显式取消令牌。
• 谨慎使用 select!：丢弃一个 future 可能会取消它。在 IO 操作或部分完成的工作周围使用时，请检查其取消安全性。

异步 trait 规则

• 如果是私有 trait 和静态分派，且调用方不需要为返回的 future 添加约束，那么在 trait 中使用原生 async fn 没问题。
• 如果需要 Send future，公共 trait 通常应将方法写为 fn name(...) -> impl Future<Output = T> + Send，或使用 trait-variant 提供本地和 Send 两种变体。
• 如果需要动态分派，公共 trait 通常需要显式的装箱 future 返回类型，例如 Pin<Box<dyn Future<Output = T> + Send + '_>>。只有在依赖和分配方面的权衡可以接受时，才将 async-trait 用作提升易用性的封装层。
• 除非 trait 有意绑定到特定运行时，否则应避免在 trait 中暴露特定执行器的类型。

审核清单

• 没有锁或借用意外跨越 .await。
• 生成的任务通过 async move 拥有其输入。
• 重要的 JoinHandle 会在关闭时等待、监控或中止。
• 阻塞工作已隔离并受到限制。
• 错误路径会保留上下文，而不是退化为 JoinError 或超时噪声。