rust-best-practices
Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. Use this skill when: (1) writing new Rust code or functions, (2) reviewing or refactoring existing Rust code, (3) deciding between borrowing vs cloning or ownership patterns, (4) implementing error handling with Result types, (5) optimizing Rust code for performance, (6) writing tests or documentation for Rust projects.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 29
- Forks
- 156
01 前言 Front Matter
- name
- rust-best-practices
- license
- MIT
- metadata
- { "author": "apollographql", "version": "1.1.1" }
- description
- Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. Use this skill when: (1) writing new Rust code or functions, (2) reviewing or refactoring existing Rust code, (3) deciding between borrowing vs cloning or ownership patterns, (4) implementing error handling with Result types, (5) optimizing Rust code for performance, (6) writing tests or documentation for Rust projects.
- allowed-tools
- Bash(cargo:*) Bash(rustc:*) Bash(rustfmt:*) Bash(clippy:*) Read Write Edit Glob Grep
- compatibility
- Rust 1.70+, Cargo
02 资源文件 9
- 参考文档references/chapter_01.md24.7 KB
- 参考文档references/chapter_02.md5.3 KB
- 参考文档references/chapter_03.md8.6 KB
- 参考文档references/chapter_04.md6.9 KB
- 参考文档references/chapter_05.md14.5 KB
- 参考文档references/chapter_06.md6.7 KB
- 参考文档references/chapter_07.md8.0 KB
- 参考文档references/chapter_08.md10.1 KB
- 参考文档references/chapter_09.md9.3 KB
03 SKILL.md 正文
Rust Best Practices
Apply these guidelines when writing or reviewing Rust code. Based on Apollo GraphQL's Rust Best Practices Handbook.
Best Practices Reference
Before reviewing, familiarize yourself with Apollo's Rust best practices. Read ALL relevant chapters in the same turn in parallel. Reference these files when providing feedback:
- Chapter 1 - Coding Styles and Idioms: Borrowing vs cloning, Copy trait, Option/Result handling, iterators, comments, when to extract a function (duplication vs. wrong abstraction)
- Chapter 2 - Clippy and Linting: Clippy configuration, important lints, workspace lint setup
- Chapter 3 - Performance Mindset: Profiling, avoiding redundant clones, stack vs heap, zero-cost abstractions
- Chapter 4 - Error Handling: Result vs panic, thiserror vs anyhow, error hierarchies
- Chapter 5 - Automated Testing: Test naming, one assertion per test, snapshot testing
- Chapter 6 - Generics and Dispatch: Static vs dynamic dispatch, trait objects
- Chapter 7 - Type State Pattern: Compile-time state safety, when to use it
- Chapter 8 - Comments vs Documentation: When to comment, doc comments, rustdoc
- Chapter 9 - Understanding Pointers: Thread safety, Send/Sync, pointer types
Quick Reference
Borrowing & Ownership
- Prefer
&Tover.clone()unless ownership transfer is required - Use
&stroverString,&[T]overVec<T>in function parameters - Small
Copytypes (≤24 bytes) can be passed by value - Use
Cow<'_, T>when ownership is ambiguous
Error Handling
- Return
Result<T, E>for fallible operations; avoidpanic!in production - Never use
unwrap()/expect()outside tests - Use
thiserrorfor library errors,anyhowfor binaries only - Prefer
?operator over match chains for error propagation
Performance
- Always benchmark with
--releaseflag - Run
cargo clippy -- -D clippy::perffor performance hints - Avoid cloning in loops; use
.iter()instead of.into_iter()for Copy types - Prefer iterators over manual loops; avoid intermediate
.collect()calls
Linting
Run regularly: cargo clippy --all-targets --all-features --locked -- -D warnings
Key lints to watch:
redundant_clone- unnecessary cloninglarge_enum_variant- oversized variants (consider boxing)needless_collect- premature collection
Use #[expect(clippy::lint)] over #[allow(...)] with justification comment.
Testing
- Name tests descriptively:
process_should_return_error_when_input_empty() - One assertion per test when possible
- Use doc tests (
///) for public API examples - Consider
cargo instafor snapshot testing generated output
Generics & Dispatch
- Prefer generics (static dispatch) for performance-critical code
- Use
dyn Traitonly when heterogeneous collections are needed - Box at API boundaries, not internally
Type State Pattern
Encode valid states in the type system to catch invalid operations at compile time:
struct Connection<State> { /* ... */ _state: PhantomData<State> }
struct Disconnected;
struct Connected;
impl Connection<Connected> {
fn send(&self, data: &[u8]) { /* only connected can send */ }
}
Documentation
//comments explain why (safety, workarounds, design rationale)///doc comments explain what and how for public APIs- Every
TODOneeds a linked issue:// TODO(#42): ... - Enable
#![deny(missing_docs)]for libraries
04 同仓库更多 Skills
business-data
暂无简介
workflow
Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.
workflow
Vercel Workflow SDK expert guidance. Use when building durable workflows, long-running tasks, API routes or agents that need pause/resume, retries, step-based execution, or crash-safe orchestration with Vercel Workflow.
verification
Full-story verification — infers what the user is building, then verifies the complete flow end-to-end: browser → API → data → response. Triggers on dev server start and 'why isn't this working' signals.
vercel-storage
Vercel storage expert guidance — Blob, Global Config (formerly Edge Config), and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.
vercel-services
Configure and troubleshoot Vercel Services for multiple frontends and backends in one project. Use when composing a polyglot or multi-service application on one Vercel deployment; defining the `services` key, service-targeted rewrites, or service bindings in `vercel.json`; or running all services with `vercel dev`.