rust-skills

Rust 最佳实践

编写高质量、符合 Rust 惯例且高度优化的 Rust 代码的综合指南。包含 26 个类别中的 265 条规则，按影响程度排序，用于指导大模型进行代码生成和重构。适用于 Rust 1.96（2024 edition）。

适用场景

在以下场景中参考这些指南：

• 编写新的 Rust 函数、结构体或模块
• 实现错误处理或异步代码
• 编写并发、并行或 unsafe 代码
• 为库设计公共 API
• 检查代码中的所有权／借用问题
• 优化内存使用或减少分配
• 调优热点路径的性能
• 重构现有 Rust 代码

按优先级划分的规则类别

优先级	类别	影响	前缀	规则数
1	所有权与借用	CRITICAL	own-	12
2	错误处理	CRITICAL	err-	12
3	内存优化	CRITICAL	mem-	17
4	不安全代码	CRITICAL	unsafe-	7
5	API 设计	HIGH	api-	17
6	Async/Await	HIGH	async-	18
7	并发	HIGH	conc-	4
8	编译器优化	HIGH	opt-	12
9	数值与算术安全	HIGH	num-	5
10	类型安全	MEDIUM	type-	13
11	Trait 与泛型设计	MEDIUM	trait-	6
12	转换	MEDIUM	conv-	3
13	Const 与编译期处理	MEDIUM	const-	4
14	Serde	MEDIUM	serde-	8
15	模式匹配	MEDIUM	pat-	5
16	宏	MEDIUM	macro-	8
17	闭包	MEDIUM	closure-	5
18	集合	MEDIUM	coll-	4
19	命名约定	MEDIUM	name-	16
20	测试	MEDIUM	test-	15
21	文档	MEDIUM	doc-	12
22	可观测性	MEDIUM	obs-	7
23	性能模式	MEDIUM	perf-	13
24	项目结构	LOW	proj-	14
25	Clippy 与 Lint	LOW	lint-	13
26	反模式	REFERENCE	anti-	15

---

快速参考

1. 所有权与借用（CRITICAL）

• own-borrow-over-clone - 优先借用 &T，而不是使用 .clone()
• own-slice-over-vec - 接受 &[T] 而不是 &Vec<T>，接受 &str 而不是 &String
• own-cow-conditional - 条件性所有权使用 Cow<'a, T>
• own-arc-shared - 线程安全的共享所有权使用 Arc<T>
• own-rc-single-thread - 单线程环境中的共享所有权使用 Rc<T>
• own-refcell-interior - 单线程代码中的内部可变性使用 RefCell<T>
• own-mutex-interior - 跨线程的内部可变性使用 Mutex<T>
• own-rwlock-readers - 读取次数远多于写入次数时使用 RwLock<T>
• own-copy-small - 为小型简单类型实现 Copy
• own-clone-explicit - 对复制成本有实际意义的类型显式使用 Clone
• own-move-large - 移动大型类型，而不是复制；移动成本高时使用 Box
• own-lifetime-elision - 遵循生命周期省略规则；仅在必要时添加显式生命周期

2. 错误处理（关键）

• err-thiserror-lib - 使用 thiserror 定义库的错误类型
• err-anyhow-app - 使用 anyhow 处理应用程序错误
• err-result-over-panic - 对可恢复的错误返回 Result<T, E>，而不是触发 panic
• err-context-chain - 使用 .context() 或 .with_context() 添加上下文
• err-no-unwrap-prod - 避免在生产代码中使用 unwrap()；使用 ?、expect() 或处理错误
• err-expect-bugs-only - 仅对表明存在 Bug 的不变量使用 expect()，不要用于用户错误
• err-question-mark - 使用 ? 运算符简洁地传播错误
• err-from-impl - 为错误转换实现 From<E>，以便使用 ? 运算符
• err-source-chain - 使用 #[source] 或 source() 方法保留错误链
• err-lowercase-msg - 错误消息以小写字母开头，末尾不加标点
• err-doc-errors - 在文档注释的 # Errors 部分说明错误条件
• err-custom-type - 为特定领域的失败定义自定义错误类型

3. 内存优化（关键）

• mem-with-capacity - 大小已知时使用 with_capacity()
• mem-smallvec - 对通常较小的集合使用 SmallVec
• mem-arrayvec - 对永不在堆上分配的固定容量集合使用 ArrayVec<T, N>
• mem-box-large-variant - 对较大的枚举变体使用 Box，以减小枚举的整体大小
• mem-boxed-slice - 对固定大小的堆数据使用 Box<[T]>，而不是 Vec<T>
• mem-thinvec - 对开销最小的可空集合使用 ThinVec<T>
• mem-clone-from - 反复克隆时使用 clone_from() 重用分配
• mem-reuse-collections - 在循环中清空并重用集合，而不是创建新集合
• mem-avoid-format - 可以使用字符串字面量时，避免使用 format!()
• mem-write-over-format - 使用 write!() 写入现有缓冲区，而不是通过 format!() 分配内存
• mem-arena-allocator - 对批量分配使用 arena 分配器
• mem-zero-copy - 使用切片和 Bytes 实现零拷贝模式
• mem-compact-string - 对内存受限的字符串存储使用紧凑字符串类型
• mem-smaller-integers - 使用大小合适的整数以减少内存占用
• mem-assert-type-size - 使用静态断言，防止类型大小意外增长
• mem-take-replace - 使用 mem::take / mem::replace 从 &mut 中移出值，而不进行克隆
• mem-drop-order - 了解并控制析构顺序：结构体字段从上到下析构，局部变量按相反顺序析构

4. 不安全代码（严重）

• unsafe-safety-comment - 在每个 unsafe 代码块上方编写 // SAFETY: 注释，并在每个 unsafe fn 中添加 # Safety 章节。
• unsafe-minimize-scope - 尽可能缩小 unsafe 代码块的范围——只标记需要不安全操作的部分，不要包含周围的安全代码。
• unsafe-miri-ci - 对每个包含 unsafe 代码的 crate，在 CI 中运行 cargo miri test。
• unsafe-maybeuninit - 使用 MaybeUninit<T> 处理未初始化内存；对于具有有效性约束的类型，绝不要使用 mem::uninitialized() 或 mem::zeroed()。
• unsafe-extern-block - 在 Rust 2024 中，将 extern 代码块写为 unsafe extern { }，并将每个条目标注为 safe 或 unsafe。
• unsafe-send-sync-manual - 手动实现 Send 或 Sync 时，记录相关不变式；优先让编译器自动推导。
• unsafe-no-mangle-unsafe - 在 Rust 2024 中，使用 #[unsafe(no_mangle)]、#[unsafe(export_name = "...")] 和 #[unsafe(link_section = "...")]，而非不带包装的属性形式。

5. API 设计（高）

• api-builder-pattern - 对复杂构造使用 Builder 模式
• api-builder-must-use - 为构建器方法标注 #[must_use]，防止结果被悄然丢弃
• api-newtype-safety - 使用新类型，避免混淆语义不同的值
• api-typestate - 使用 typestate 模式，在类型系统中编码状态机不变式
• api-sealed-trait - 使用密封 trait，在允许使用的同时阻止外部实现
• api-extension-trait - 使用扩展 trait 为外部类型添加方法
• api-parse-dont-validate - 在边界处解析为经过验证的类型
• api-impl-into - 接受 impl Into<T> 以提供灵活的 API，并为转换实现 From<T>
• api-impl-asref - 只需借用内部数据时使用 AsRef<T>
• api-must-use - 忽略结果可能导致错误时，为类型和函数标注 #[must_use]
• api-non-exhaustive - 为公共枚举和结构体使用 #[non_exhaustive]，以保持向前兼容
• api-from-not-into - 实现 From<T>，而非 Into<U>——使用 From 可自动获得 Into
• api-default-impl - 为具有合理默认值的类型实现 Default
• api-common-traits - 为公共类型实现标准 trait（Debug、Clone、PartialEq 等）
• api-serde-optional - 将 serde 设为功能标志，而非库 crate 的硬依赖
• api-impl-fromiterator - 为集合类型实现 FromIterator 和 Extend，并为三种引用形式实现 IntoIterator
• api-operator-overload - 仅当语义自然且不会令人意外时才重载运算符

6. 异步/等待（HIGH）

• async-tokio-runtime - 根据工作负载适当配置 Tokio 运行时
• async-no-lock-await - 绝不要在 .await 期间持有 Mutex/RwLock
• async-spawn-blocking - 对 CPU 密集型工作使用 spawn_blocking
• async-tokio-fs - 在异步代码中使用 tokio::fs，而非 std::fs
• async-cancellation-token - 使用 CancellationToken 实现平滑关闭和任务取消
• async-join-parallel - 对并发的独立 Future 使用 join! 或 try_join!
• async-try-join - 对并发的可失败操作使用 try_join!，遇到错误时提前返回
• async-select-racing - 使用 select! 竞争多个 Future，并处理最先完成的那个
• async-bounded-channel - 使用有界通道施加背压，避免内存无限增长
• async-mpsc-queue - 使用 mpsc 通道在任务间创建异步消息队列
• async-broadcast-pubsub - 在所有订阅者都应接收所有消息时，使用 broadcast 通道实现发布/订阅
• async-watch-latest - 使用 watch 通道与多个观察者共享最新值
• async-oneshot-response - 对请求-响应模式使用 oneshot 通道
• async-joinset-structured - 使用 JoinSet 管理动态的已生成任务集合
• async-clone-before-await - 在 await 点之前克隆 Arc/Rc 数据，避免在挂起期间持有引用
• async-fn-in-trait - 在 trait 中使用原生 async fn（稳定版 1.75），而非 async_trait 宏
• async-async-fn-bounds - 使用 AsyncFn/AsyncFnMut/AsyncFnOnce 约束，而非 F: Fn() -> Fut, Fut: Future
• async-cancel-safety - 确保 tokio::select! 分支中使用的 Future 支持取消安全

7. 并发（HIGH）

• conc-rayon-par-iter - 对 CPU 密集型数据并行处理使用 rayon 的 par_iter()
• conc-scoped-threads - 使用 std::thread::scope 在线程间借用栈数据
• conc-atomic-ordering - 对每个原子操作使用正确且最弱的内存 Ordering
• conc-thread-local - 优先使用搭配 Cell/RefCell 的 thread_local!，而非 static mut

8. 编译器优化（高）

• opt-inline-small - 对小型热点函数使用 #[inline]
• opt-inline-always-rare - 谨慎使用 #[inline(always)]——仅用于经性能分析证实的关键热点路径
• opt-inline-never-cold - 对错误路径和极少执行的代码使用 #[inline(never)] 和 #[cold]
• opt-cold-unlikely - 使用 #[cold] 标记不太可能执行的代码路径，以帮助编译器优化
• opt-likely-hint - 使用代码结构提示可能执行的分支；在 nightly 上使用内建函数
• opt-lto-release - 在发布构建中启用 LTO
• opt-codegen-units - 将 codegen-units = 1 设置为在发布构建中实现最大优化
• opt-pgo-profile - 使用基于性能分析的优化（PGO）来实现最高性能
• opt-target-cpu - 在已知的部署目标上使用 target-cpu=native 以实现最高性能
• opt-bounds-check - 在热点路径中使用可消除边界检查的迭代器和模式
• opt-simd-portable - 使用可移植 SIMD 在不同架构上执行向量化操作
• opt-cache-friendly - 组织数据，以实现缓存友好的访问模式

9. 数值与算术安全性（高）

• num-overflow-explicit - 显式处理整数溢出：checked_/saturating_/wrapping_/overflowing_
• num-cast-try-from - 避免在窄化转换中使用 as；扩大转换使用 From，窄化转换使用 TryFrom
• num-float-compare - 不要使用 == 比较浮点数；使用容差，并在排序时使用 total_cmp
• num-saturating-clamp - 使用 clamp 和饱和算术限制数值范围
• num-nonzero - 使用 NonZero* 类型禁止零值，并启用利基优化

10. 类型安全（中）

• type-newtype-ids - 使用新类型封装 ID：UserId(u64)
• type-newtype-validated - 使用新类型在构造时强制执行验证
• type-enum-states - 使用枚举表示互斥状态
• type-option-nullable - 对可能不存在的值使用 Option<T>
• type-result-fallible - 对可能失败的操作使用 Result<T, E>
• type-phantom-marker - 使用 PhantomData 表达类型关系，且不产生运行时开销
• type-never-diverge - 对永不返回的函数使用 !（never 类型）
• type-generic-bounds - 仅在需要时添加 trait 约束；为提高可读性，优先使用 where 子句
• type-no-stringly - 避免使用字符串类型的 API；改用枚举、新类型或经过验证的类型
• type-repr-transparent - 在 FFI 场景中为新类型使用 #[repr(transparent)]
• type-deref-coercion - 仅为智能指针类型和透明包装类型实现 Deref/DerefMut
• type-display-vs-debug - 面向用户的输出使用 Display，诊断信息使用 Debug；切勿混用
• type-numeric-fmt - 为数值新类型实现 LowerHex、UpperHex、Octal 和 Binary

11. Trait 与泛型设计（中等）

• trait-associated-type-vs-generic - 当每个实现恰好有一个输出类型时，使用关联类型；当某个类型可以针对多种输入类型实现该 trait 时，使用泛型参数
• trait-blanket-impl - 使用 blanket impl impl<T: Bound> Trait for T，为所有满足约束的类型提供行为
• trait-coherence-newtype - 遵守孤儿规则；将外部类型包装为 newtype，以便为其实现外部 trait
• trait-default-methods - 通过少数必需方法及基于这些方法的默认方法来定义 trait
• trait-dyn-vs-generic - 有意识地选择静态分发（泛型 / impl Trait）还是动态分发（dyn Trait）
• trait-object-safety - 需要使用 dyn Trait 时，确保 trait 与 dyn 兼容（对象安全）

12. 类型转换（中等）

• conv-tryfrom-fallible - 对可能失败的类型转换实现 TryFrom，而不是使用临时的转换函数
• conv-fromstr-parsing - 实现 FromStr，以便对字符串到类型的转换使用 str::parse
• conv-asmut-mutable - 使用 impl AsMut<T> 接受灵活的可变借用输入，而不是具体的可变引用

13. 常量与编译时计算（中等）

• const-block - 使用内联 const { } 块进行编译时求值和断言
• const-fn - 函数可在编译时运行时，将其声明为 const fn
• const-generics - 使用 const 泛型 <const N: usize>，按值进行参数化
• const-vs-static - 内联值使用 const，单个具有固定地址的实例使用 static

14. Serde（中等）

• serde-rename-all - 使用 #[serde(rename_all = ...)] 匹配外部命名约定
• serde-default-compat - 对可选且向后兼容的字段使用 #[serde(default)]
• serde-skip-empty - 使用 skip_serializing_if 忽略空字段
• serde-flatten - 使用 #[serde(flatten)] 内联嵌套结构体或捕获额外键
• serde-enum-representation - 有意识地选择枚举标记方式：外部标记、内部标记、相邻标记或无标记
• serde-deny-unknown-fields - 使用 #[serde(deny_unknown_fields)] 拒绝意外的键
• serde-custom-with - 使用 with / serialize_with / deserialize_with 自定义字段的序列化与反序列化
• serde-try-from-validate - 使用 #[serde(try_from = "Raw")] 在反序列化时进行验证

15. 模式匹配（中等）

• pat-let-else - 使用 let ... else 提前返回并提取模式匹配结果
• pat-matches-macro - 使用 matches!() 进行布尔模式测试
• pat-if-let-chains - 使用 if let 链组合模式绑定与条件
• pat-exhaustive-enum - 穷尽匹配所有权枚举；避免使用会隐藏新增变体的兜底 _
• pat-at-bindings - 使用 @ 绑定，在将值与模式匹配的同时捕获该值

16. 宏（中）

• macro-prefer-functions - 只有函数或泛型无法表达需求时，才使用宏
• macro-rules-hygiene - 依赖 macro_rules! 的卫生机制，并使用 $crate 引用 crate 中的条目
• macro-fragment-specifiers - 尽可能使用精确的片段说明符进行捕获，而不是原始的 :tt
• macro-export-crate-path - 使用 #[macro_export] 导出声明式宏，并提供清晰的导入路径
• macro-private-helpers - 将宏生成的辅助条目隐藏在 #[doc(hidden)] pub mod __private 后
• macro-proc-two-crate - 将过程宏放入专用的 proc-macro = true crate，并从 facade 重新导出
• macro-proc-syn-quote - 使用 syn、quote 和 proc-macro2 构建过程宏
• macro-proc-error-spans - 将过程宏错误报告为带有跨度的编译错误，切勿通过 panic 报错

17. 闭包（中）

• closure-fn-trait-bounds - 回调只需满足其所需的最宽松 Fn trait（FnOnce ⊇ FnMut ⊇ Fn）
• closure-impl-fn-return - 将闭包作为 impl Fn/FnMut/FnOnce 返回，而不是 Box<dyn Fn>
• closure-move-capture - 对生命周期超出当前作用域的闭包使用 move；在 move 前克隆，以保留原值
• closure-static-vs-dyn - 热路径回调接受泛型 impl Fn；若要减少代码体积或存储回调，则使用 &dyn Fn/Box<dyn Fn>
• closure-disjoint-capture - 只捕获实际使用的内容；充分利用 edition-2021 的闭包不相交捕获

18. 集合（中）

• coll-binaryheap - 对于优先队列或反复提取最大值，使用 BinaryHeap
• coll-map-choice - 根据访问模式选择映射：HashMap（速度快、无序）、BTreeMap（有序／范围查询）、IndexMap（按插入顺序）
• coll-seq-choice - 默认使用 Vec；队列／双端队列行为使用 VecDeque；避免使用 LinkedList
• coll-set-membership - 使用 HashSet/BTreeSet 进行成员测试和去重，而不是线性遍历 Vec::contains

19. 命名约定（中）

• name-types-camel - 类型、特征和枚举名称使用 UpperCamelCase
• name-variants-camel - 枚举变体使用 UpperCamelCase
• name-funcs-snake - 函数、方法、变量和模块使用 snake_case
• name-consts-screaming - 常量和静态变量使用 SCREAMING_SNAKE_CASE
• name-lifetime-short - 使用简短且惯用的生命周期名称：'a、'b、'de、'src
• name-type-param-single - 类型参数使用单个大写字母：T、E、K、V
• name-as-free - as_ 前缀：转换为自由引用
• name-to-expensive - 对需要分配或计算的开销较大的转换使用 to_ 前缀
• name-into-ownership - 对会消耗所有权的转换使用 into_ 前缀
• name-no-get-prefix - 简单的获取器省略 get_ 前缀
• name-is-has-bool - 返回布尔值的方法使用 is_、has_、can_、should_ 前缀
• name-iter-convention - 迭代器方法使用 iter/iter_mut/into_iter
• name-iter-method - 迭代器方法统一命名为 iter()、iter_mut() 和 into_iter()
• name-iter-type-match - 迭代器类型的名称应与其源方法对应
• name-acronym-word - 标识符中的缩写按单词处理：使用 HttpServer，而非 HTTPServer
• name-crate-no-rs - crate 名称不要添加 -rs 或 -rust 后缀

20. 测试（中）

• test-cfg-test-module - 在每个模块中使用 #[cfg(test)] mod tests { } 编写单元测试
• test-use-super - 在测试模块中使用 use super::*; 访问父模块中的项目
• test-integration-dir - 将集成测试放在 tests/ 目录中
• test-descriptive-names - 使用能说明测试内容的描述性测试名称
• test-arrange-act-assert - 将测试清晰地划分为 Arrange、Act、Assert 部分
• test-proptest-properties - 使用 proptest 进行基于属性的测试
• test-mockall-mocking - 使用 mockall 模拟特征
• test-mock-traits - 依赖项使用特征，以便在测试中进行模拟
• test-fixture-raii - 使用 RAII 模式（Drop 特征）自动清理测试
• test-tokio-async - 使用 #[tokio::test] 编写异步测试
• test-should-panic - 使用 #[should_panic] 测试代码是否按预期发生 panic
• test-criterion-bench - 使用 criterion 进行基准测试
• test-doctest-examples - 将文档示例保留为可执行的文档测试
• test-loom-concurrency - 使用 loom 穷举测试无锁和并发代码
• test-snapshot-testing - 对复杂或序列化输出使用快照测试（insta）

21. 文档（MEDIUM）

• doc-all-public - 使用 /// 文档注释为所有公开项编写文档
• doc-module-inner - 使用 //! 编写模块级文档
• doc-examples-section - 添加包含可运行代码的 # Examples
• doc-errors-section - 为可能失败的函数添加 # Errors 部分
• doc-panics-section - 为可能 panic 的函数添加 # Panics 部分
• doc-safety-section - 为不安全函数添加 # Safety 部分
• doc-question-mark - 在示例中使用 ?，而非 .unwrap()
• doc-hidden-setup - 使用 # 前缀隐藏示例中的准备代码
• doc-intra-links - 使用文档内链接引用类型和项
• doc-link-types - 使用文档内链接关联相关类型和函数
• doc-cargo-metadata - 为已发布的 crate 填写 Cargo.toml 元数据
• doc-crate-readme - 使用 #![doc = include_str!("../README.md")] 统一 README 与 crate 根文档

22. 可观测性（MEDIUM）

• obs-tracing-over-log - 使用 tracing 进行结构化、带跨度上下文的诊断，而非 println! 或裸 log
• obs-library-facade - 库通过 tracing/log 门面输出日志，绝不安装订阅器
• obs-structured-fields - 记录结构化的键值字段，而非将值插入消息字符串
• obs-instrument-spans - 使用 #[tracing::instrument] 和跨度为异步任务与请求附加上下文
• obs-levels-filter - 合理使用日志级别，并通过 EnvFilter / RUST_LOG 进行过滤
• obs-error-chain - 记录错误的完整来源链，并确保每个错误只记录一次
• obs-no-sensitive-data - 绝不记录机密或个人身份信息（PII）；对其进行脱敏或跳过

23. 性能模式（MEDIUM）

• perf-iter-over-index - 优先使用迭代器，而非手动索引
• perf-iter-lazy - 保持迭代器惰性，仅在需要时收集
• perf-collect-once - 不要收集临时迭代器
• perf-entry-api - 使用 map 的 entry API 执行插入或更新
• perf-drain-reuse - 使用 drain 重用分配
• perf-extend-batch - 批量插入时使用 extend
• perf-chain-avoid - 避免在热点循环中使用 chain
• perf-collect-into - 使用 collect_into 重用容器
• perf-black-box-bench - 在基准测试中使用 black_box
• perf-release-profile - 优化发布配置
• perf-profile-first - 优化前先进行性能分析
• perf-ahash - 无需防范 DoS 时，使用更快的哈希器（ahash / FxHashMap）
• perf-io-buffering - 对许多小型操作使用 BufReader / BufWriter 包装 Read / Write

24. 项目结构（LOW）

• proj-lib-main-split - 保持 main.rs 简洁，将逻辑放在 lib.rs 中
• proj-mod-by-feature - 按功能而非类型组织模块
• proj-flat-small - 小型项目保持扁平结构
• proj-mod-rs-dir - 多文件模块使用 mod.rs
• proj-pub-crate-internal - 内部 API 使用 pub(crate)
• proj-pub-super-parent - 仅允许父级访问时使用 pub(super)
• proj-pub-use-reexport - 使用 pub use 提供简洁的公共 API
• proj-prelude-module - 创建 prelude 模块，以便导入常用内容
• proj-bin-dir - 将多个二进制文件放在 src/bin/ 中
• proj-workspace-large - 大型项目使用工作区
• proj-workspace-deps - 使用工作区依赖继承，确保各 crate 版本一致
• proj-feature-additive - 将 Cargo 功能设计为严格的增量式功能
• proj-msrv-declare - 在 Cargo.toml 中声明 rust-version（MSRV），并在 CI 中测试
• proj-build-rs-minimal - 保持 build.rs 简洁、确定且幂等

25. Clippy 与 Lint（LOW）

• lint-deny-correctness - #![deny(clippy::correctness)]
• lint-warn-suspicious - 启用 clippy::suspicious，以发现可能的错误
• lint-warn-style - 启用 clippy::style，以编写符合惯用风格的代码
• lint-warn-complexity - 启用 clippy::complexity，以简化代码
• lint-warn-perf - 启用 clippy::perf，以改进性能
• lint-pedantic-selective - 有选择地启用 clippy::pedantic
• lint-missing-docs - 对缺少文档的公共项发出警告
• lint-unsafe-doc - 要求为 unsafe 代码块编写文档
• lint-cargo-metadata - 为已发布的 crate 启用 clippy::cargo
• lint-rustfmt-check - 在 CI 中运行 cargo fmt --check
• lint-workspace-lints - 在工作区级别配置 lint，以确保统一执行
• lint-cfg-check - 启用 unexpected_cfgs 并声明已知 cfg，以发现功能门拼写错误
• lint-clippy-nursery-selected - 有选择地启用高价值的 clippy::nursery lint，而非启用整个 lint 组

26. 反模式（参考）

• anti-unwrap-abuse - 不要在生产代码中使用 .unwrap()
• anti-expect-lazy - 对可恢复的错误不要使用 expect
• anti-clone-excessive - 可以借用时不要克隆
• anti-lock-across-await - 不要在 await 点之间持有锁
• anti-string-for-str - 可以使用 &str 时不要接受 &String
• anti-vec-for-slice - 可以使用 &[T] 时不要接受 &Vec
• anti-index-over-iter - 可以使用迭代器时不要使用索引
• anti-panic-expected - 对预期发生或可恢复的错误不要触发 panic
• anti-empty-catch - 不要默默忽略错误
• anti-over-abstraction - 不要使用过多泛型进行过度抽象
• anti-premature-optimize - 未进行性能分析前不要优化
• anti-type-erasure - 可以使用 impl Trait 时不要使用 Box
• anti-format-hot-path - 不要在热点路径中使用 format!
• anti-collect-intermediate - 不要收集中间迭代器
• anti-stringly-typed - 枚举或新类型可以提供类型安全时，不要使用字符串

---

推荐的 Cargo.toml 设置

[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
panic = "abort"
strip = true

[profile.bench]
inherits = "release"
debug = true
strip = false

[profile.dev]
opt-level = 0
debug = true

[profile.dev.package."*"]
opt-level = 3  # Optimize dependencies in dev

---

使用方法

此技能提供规则标识符，便于快速参考。生成或审查 Rust 代码时：

1. 检查相关类别，根据任务类型选择
2. 应用规则，使用匹配的前缀
3. 确定优先级：CRITICAL > HIGH > MEDIUM > LOW
4. 阅读规则文件，在 rules/ 中查看详细示例

按任务应用规则

任务	主要类别
新函数	own-、err-、name-、pat-
新结构体/API	api-、type-、conv-、doc-
异步代码	async-、own-
并发/并行	conc-、async-、own-
不安全代码	unsafe-、type-、test-
错误处理	err-、api-、pat-
类型转换	conv-、api-
序列化（serde）	serde-、type-、api-
数值/算术	num-、type-
宏/代码生成	macro-、anti-
闭包/回调	closure-、type-
日志记录/可观测性	obs-、err-
内存优化	mem-、own-、perf-
性能调优	opt-、mem-、perf-
代码审查	anti-、lint-

---

来源与致谢

此技能综合了官方 Rust 指南、知名书籍和广泛使用的 crate 中的实践经验。它与 Rust 项目或任何 crate 作者均无关联，也未获其认可；文中内容和代码示例均为原创。

官方 Rust 文档

• Rust 参考手册
• Rust API 指南
• Rustonomicon（不安全代码）
• Rust 2024 版本指南
• Cargo 手册
• 标准库文档和发行说明

书籍与指南

• Rust 性能手册 — Nicholas Nethercote
• Rust 设计模式 — rust-unofficial
• Rust 原子操作与锁 — Mara Bos
• Effective Rust — David Drysdale

工具

• Clippy lint 文档
• Miri

用于研究惯用写法的真实代码库

• ripgrep、tokio、serde、clap、polars、axum、cargo、hyper、bevy、rayon，以及 dtolnay 的 crate（thiserror、anyhow、syn）

本项目采用 MIT 许可证。引用的上游材料仍受各自许可证约束（官方 Rust 文档和 API 指南采用 MIT / Apache-2.0 双重许可）。