rust-system-event-driven

Rust 事件驱动系统最佳实践

Rust 事件驱动系统编程综合最佳实践指南。包含 8 个类别中的 42 条规则，并按影响程度排序，指导异步运行时使用、通道通信、线程处理、网络和终端处理。

适用场景

在以下情况下参考这些指南：

• 使用 Tokio 或 async-std 构建异步应用
• 实现网络服务端或客户端
• 编写终端用户界面（TUI）
• 管理并发任务和共享状态
• 处理 Unix 信号和优雅关闭

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	异步运行时模式	严重	async-
2	通道通信	严重	chan-
3	线程与同步	高	sync-
4	套接字与网络 I/O	高	net-
5	终端与 TTY 处理	中高	term-
6	信号与进程控制	中	sig-
7	文件 I/O 流式处理	中	io-
8	事件循环架构	中低	loop-

快速参考

1. 异步运行时模式（严重）

• async-spawn-blocking - 使用 spawn_blocking 执行 CPU 密集型工作
• async-select-biased - 使用 biased select 处理优先级
• async-no-std-block - 避免在异步上下文中调用 std 阻塞函数
• async-cancellation-safe - 设计支持安全取消的异步操作
• async-task-local - 使用任务本地存储保存请求上下文
• async-structured-concurrency - 使用 JoinSet 实现结构化并发

2. 通道通信（严重）

• chan-bounded-backpressure - 使用有界通道实现背压
• chan-oneshot-response - 使用 oneshot 通道实现请求-响应
• chan-broadcast-fanout - 使用广播通道实现扇出
• chan-watch-state - 使用 watch 通道共享状态
• chan-graceful-shutdown - 使用通道关闭实现优雅关闭

3. 线程与同步（高）

• sync-arc-mutex-shared - 使用 Arc 管理共享可变状态
• sync-rwlock-read-heavy - 在读密集型工作负载中使用 RwLock
• sync-atomic-counters - 使用原子操作处理简单计数器和标志
• sync-avoid-lock-await - 避免在 await 期间持有 std Mutex
• sync-semaphore-limit - 使用 Semaphore 限制并发
• sync-parking-lot - 高竞争锁使用 parking_lot

4. 套接字与网络 I/O（高）

• net-split-reader-writer - 将套接字拆分为读写两部分
• net-framing-codec - 在基于消息的协议中使用帧
• net-connection-pool - 为重复连接使用连接池
• net-timeout-all-io - 为所有网络操作添加超时
• net-tcp-nodelay - 为低延迟协议设置 TCP_NODELAY
• net-graceful-disconnect - 实现优雅的连接关闭

5. 终端与 TTY 处理（中高）

• term-raw-mode-restore - 退出时始终恢复终端状态
• term-alternate-screen - 全屏应用使用备用屏幕
• term-async-event-stream - 使用异步事件流处理终端输入
• term-buffered-output - 缓冲终端输出以提升性能
• term-handle-resize - 处理终端大小调整事件

6. 信号与进程控制（中）

• sig-ctrl-c-graceful - 处理 Ctrl-C，以便优雅关闭
• sig-unix-signals - 异步处理 Unix 信号
• sig-child-reap - 回收子进程，避免产生僵尸进程
• sig-timeout-shutdown - 设置关闭超时时间，以强制退出

7. 文件 I/O 流式处理（中）

• io-async-file-ops - 在异步上下文中使用异步文件操作
• io-stream-large-files - 流式处理大文件，而不是一次性全部加载
• io-copy-bidirectional - 使用 copy_bidirectional 进行代理
• io-pipe-communication - 使用管道进行进程间通信
• io-flush-before-read - 在等待响应前刷新写入内容

8. 事件循环架构（低至中）

• loop-actor-model - 为有状态组件使用 Actor 模式
• loop-event-types - 使用类型化事件，而非动态分派
• loop-state-machine - 将协议状态建模为类型安全的状态机
• loop-layered-architecture - 将 I/O 与业务逻辑分离
• loop-cancellation-token - 使用 CancellationToken 协调关闭

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息