AI Skills
rust-best-practices

rust-best-practices

基于 Apollo GraphQL 最佳实践手册编写地道 Rust 代码的指南。在以下场景使用此技能： (1) 编写新的 Rust 代码或函数， (2) 审查或重构现有 Rust 代码， (3) 在借用与克隆或所有权模式之间做决策， (4) 使用 Result 类型实现错误处理， (5) 优化 Rust 代码性能， (6) 为 Rust 项目编写测试或文档。

90Star
10Fork
更新于 2026/6/4
获取 Skill源代码

相关 Skills

golang-dependency-injection2261appinsights-instrumentation1196weather38万
SKILL.md
readonly只读
name
rust-best-practices
description

基于 Apollo GraphQL 最佳实践手册编写地道 Rust 代码的指南。在以下场景使用此技能： (1) 编写新的 Rust 代码或函数， (2) 审查或重构现有 Rust 代码， (3) 在借用与克隆或所有权模式之间做决策， (4) 使用 Result 类型实现错误处理， (5) 优化 Rust 代码性能， (6) 为 Rust 项目编写测试或文档。

Rust 最佳实践

在编写或审查 Rust 代码时应用这些指南。基于 Apollo GraphQL 的 Rust 最佳实践手册。

最佳实践参考

在审查之前，熟悉 Apollo 的 Rust 最佳实践。在同一轮中并行阅读所有相关章节。在提供反馈时参考这些文件：

快速参考

借用与所有权

  • 优先使用 &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() 调用

Linting

定期运行：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]) { /* 只有已连接才能发送 */ }
}

文档

  • // 注释解释为什么（安全性、变通方法、设计理由）
  • /// 文档注释解释公共 API 的是什么和如何做
  • 每个 TODO 需要关联一个问题：// TODO(#42): ...
  • 为库启用 #![deny(missing_docs)]