编写或审查 Rust 代码时遵循 Apollo…

在编写、重构或审查 Rust 代码时，按 Apollo Rust 最佳实践手册规范借用、错误处理、性能、lint、测试、泛型与文档。

适用场景

解决思路

1. 审查前先并行阅读 references 下全部相关章节：chapter_01（编码风格与惯用法：借用 vs 克隆、Copy trait、Option/Result、迭代器、注释、何时抽取函数）、chapter_02（Clippy 与 lint 配置）、chapter_03（性能思维：profiling、避免冗余克隆、栈 vs 堆、零成本抽象）、chapter_04（错误处理：Result vs panic、thiserror vs anyhow、错误层级）、chapter_05（自动化测试：命名、单断言、快照测试）、chapter_06（泛型与分发：静态 vs 动态分发、trait 对象）、chapter_07（类型状态模式）、chapter_08（注释 vs 文档）、chapter_09（指针与线程安全、Send/Sync）
2. 借用与所有权：除非需要转移所有权，优先用 `&T` 而非 `.clone()`
3. 函数参数优先用 `&str` 而非 `String`、`&[T]` 而非 `Vec<T>`
4. 小的 `Copy` 类型（≤24 字节）可按值传递
5. 所有权不明确时使用 `Cow<'_, T>`
6. 错误处理：可失败操作返回 `Result<T, E>`，生产代码避免 `panic!`
7. 测试之外绝不使用 `unwrap()`/`expect()`
8. 库错误用 `thiserror`，仅二进制用 `anyhow`
9. 错误传播优先用 `?` 运算符而非 match 链
10. 性能：始终用 `--release` 标志做基准测试
11. 运行 `cargo clippy -- -D clippy::perf` 获取性能提示
12. 避免在循环中克隆；对 Copy 类型用 `.iter()` 而非 `.into_iter()`
13. 优先用迭代器而非手写循环；避免中间 `.collect()` 调用
14. Lint：定期运行 `cargo clippy --all-targets --all-features --locked -- -D warnings`
15. 关注关键 lint：`redundant_clone`（不必要克隆）、`large_enum_variant`（过大变体，考虑装箱）、`needless_collect`（过早收集）
16. 用 `#[expect(clippy::lint)]` 替代 `#[allow(...)]`，并附上理由注释
17. 测试：用描述性命名，如 `process_should_return_error_when_input_empty()`
18. 尽可能每个测试只放一个断言
19. 公共 API 示例使用文档测试（`///`）
20. 生成输出的快照测试可考虑 `cargo insta`
21. 泛型与分发：性能关键代码优先用泛型（静态分发）
22. 仅在需要异构集合时使用 `dyn Trait`
23. 在 API 边界装箱，而非内部装箱
24. 类型状态模式：用类型系统编码合法状态，在编译期捕获非法操作，例如 `struct Connection<State> { _state: PhantomData<State> }`，定义 `Disconnected`/`Connected`，仅在 `impl Connection<Connected>` 上实现 `send`
25. 文档：`//` 注释解释 *为什么*（安全性、变通、设计理由）
26. `///` 文档注释解释公共 API 的 *是什么* 和 *怎么用*
27. 每个 `TODO` 都要关联 issue：`// TODO(#42): ...`
28. 库中启用 `#![deny(missing_docs)]`

适用边界 · 注意事项

• 非 Rust 项目或非 Rust 代码审查场景
• 需要 Rust 1.70 以下版本或非 Cargo 构建系统的项目