rust-best-practices

Rust 最佳实践

使用现有的 crate 设计、edition、rust-toolchain.toml 和 Cargo.toml 中的 rust-version（MSRV）。参考示例可能使用较新的功能：采用前请确认其受支持；不要仅为遵循示例而升级工具链或添加 crate。

阅读与所更改的 Rust 问题相关的参考文档。局部修改不需要涵盖每个类别、引入新的测试框架或审查整个工作区。

主题	参考文档	适用场景
编码风格	references/coding-style.md	命名、导入、迭代器、注释、字符串处理、宏
错误处理	references/error-handling.md	Result、Option、?、thiserror、anyhow、自定义错误、异步错误
所有权与指针	references/ownership-and-pointers.md	生命周期、借用、智能指针、Pin、Cow、内部可变性
Trait 与泛型	references/traits-and-generics.md	Trait 设计、分派、GAT、密封 Trait、类型状态模式
异步与并发	references/async-and-concurrency.md	Tokio、通道、流、关闭、运行时配置、异步 Trait
同步并发	references/concurrency-sync.md	原子操作、Mutex、RwLock、锁顺序、Send/Sync、内存顺序
测试	references/testing.md	单元/集成/文档测试、快照、proptest、mockall、基准测试、模糊测试
性能	references/performance.md	性能分析、火焰图、克隆、栈与堆、迭代器、内存分配
Clippy 与 Lint	references/clippy-and-linting.md	Clippy 配置、关键 lint、工作区设置、#[expect] 与 #[allow]
文档	references/documentation.md	文档注释、rustdoc、文档 lint、覆盖率检查清单

工程基本要求

• 有意地借用或转移所有权；需要独立所有权时再克隆。优先选择清晰的所有权处理方式，而非依据数值大小规则或避免所有内存分配。
• 使用 Result 处理可能失败的操作，并保留有用的错误上下文。仅在违反程序员不变量时使用 panic/assertion；对外部输入进行验证，并返回可恢复的错误。
• 错误类型、分派方式和依赖项应符合现有的公开契约。thiserror、anyhow、Tokio 和第三方同步 crate 都是可选方案，并非必须添加。
• 缩短锁的持有时间，维持锁顺序，并考虑取消、关闭和生成任务的所有权。不要在 .await 期间持有同步锁。
• 将 Send/Sync 约束和原子顺序视为正确性属性。只有具备有效的同步依据时，才选择较弱的内存顺序；进行以性能为导向的重写前先做基准测试。
• 在负责维护相应不变量的测试套件中添加行为测试。只有在契约或风险需要时，才添加类型级、属性、模糊、快照或基准测试。
• 运行仓库要求的、适用范围内的格式化、Lint 和测试命令；复用有效的验证结果。是否运行整个工作区/所有功能，以及文档覆盖率规则，遵循项目政策。检查该 crate 实际支持的功能组合。