用途
Rust Best Practices 是一个用于指导编写地道 Rust 代码的技能，基于 Apollo GraphQL 的 Rust 最佳实践手册。它适用于以下场景：编写新的 Rust 代码或函数，以及审查 Rust 代码。
主要能力
该技能提供最佳实践参考，在审查代码前，建议先熟悉 Apollo 的 Rust 最佳实践，并在同一轮中并行阅读所有相关章节。提供反馈时可参考以下文件：
- 第 1 章 - 编码风格与惯用法：借用与克隆、Copy trait、Option/Result 处理、迭代器、注释
- 第 2 章 - Clippy 与 Lint：Clippy 配置、重要 lint、工作区 lint 设置
- 第 3 章 - 性能思维：性能分析、避免冗余克隆、栈与堆、零成本抽象
- 第 4 章 - 错误处理：Result 与 panic、thiserror 与 anyhow、错误层级
- 第 5 章 - 自动化测试：测试命名、每个测试一个断言、快照测试
- 第 6 章 - 泛型与分发：静态与动态分发、trait 对象
- 第 7 章 - 类型状态模式：编译期状态安全、何时使用
- 第 8 章 - 注释与文档：何时注释、文档注释、rustdoc
- 第 9 章 - 理解指针：线程安全、Send/Sync、指针类型
快速参考
借用与所有权
- 优先使用 &T 而非 .clone()，除非需要转移所有权
- 函数参数中使用 &str 而非 String，使用 &[T] 而非 Vec<T>
- 小型 Copy 类型（≤24 字节）可按值传递
- 当所有权不明确时使用 Cow<'_, T>
错误处理
- 对可能失败的操作返回 Result<T, E>；避免在生产环境使用 panic!
- 绝不在测试之外使用 unwrap()/expect()
- 库错误使用 thiserror，二进制程序使用 anyhow
- 错误传播优先使用 ? 运算符而非 match 链
性能
- 始终使用 --release 标志进行基准测试
- 运行 cargo clippy -- -D clippy::perf 获取性能提示
- 避免在循环中克隆；对 Copy 类型使用 .iter() 而非 .into_iter()
- 优先使用迭代器而非手动循环；避免中间 .collect() 调用
Lint
- 定期运行：cargo clippy --all-targets --all-features --locked -- -D warnings
- 需要关注的关键 lint：
- redundant_clone - 不必要的克隆
- large_enum_variant - 过大的变体（考虑装箱）
- needless_collect - 过早收集
- 使用 #[expect(clippy::lint)] 而非 #[allow(...)]，并附上理由注释
测试
- 使用描述性测试命名：process_should_return_error_when_input_empty()
- 尽可能每个测试一个断言
- 对公共 API 示例使用文档测试（///）
- 考虑使用 cargo insta 进行生成输出的快照测试
泛型与分发
- 对性能关键代码优先使用泛型（静态分发）
- 仅在需要异构集合时使用 dyn Trait
- 在 API 边界装箱，而非内部
类型状态模式
在类型系统中编码有效状态，以在编译期捕获无效操作：
struct Connection<State> { /* ... */ _state: PhantomData<State> }
struct Disconnected;
struct Connected;
impl Connection<Connected> {
fn send(&self, data: &[u8]) { /* only connected can send */ }
}
文档
- // 注释解释为什么（安全性、变通方法、设计理由）
- /// 文档注释解释公共 API 的做什么和怎么做
- 每个 TODO 都需要链接 issue：// TODO(#42): ...
- 为库启用 #![deny(missing_docs)]
使用方式
在编写或审查 Rust 代码时应用这些指南。审查前先熟悉 Apollo 的 Rust 最佳实践，并行阅读所有相关章节，并在提供反馈时引用这些文件。
适用场景
适用于编写新的 Rust 代码或函数，以及审查 Rust 代码。
限制
暂未提供关于收费、价格、平台或效果的具体信息。