rust-idioms

Rust 社区 Rust 重构最佳实践

面向 Rust 应用的全面重构与惯用模式指南，由 Rust 社区维护。包含 8 个类别的 44 条规则，并按影响程度排序，用于指导自动化重构与代码生成。

适用场景

在以下情况下参考这些指南：

• 编写具有强类型保证的新 Rust 代码
• 重构所有权与借用模式
• 设计错误处理策略
• 使用 trait 和泛型创建公共 API
• 组织模块并控制可见性

按优先级划分的规则类别

优先级	类别	影响	前缀
1	类型安全与 Newtype 模式	严重	type-
2	所有权与借用	严重	own-
3	错误处理模式	高	err-
4	API 设计与 Trait	高	api-
5	模块与可见性	中高	mod-
6	转换 Trait	中	conv-
7	惯用模式	中	idiom-
8	迭代器与集合	中低	iter-

快速参考

1. 类型安全与 Newtype 模式（严重）

• type-newtype-units - 使用 Newtype 模式确保单位安全
• type-newtype-invariants - 在 Newtype 构造器中编码不变量
• type-non-exhaustive-enums - 使用非穷尽枚举以支持扩展
• type-phantom-data - 使用 PhantomData 表示类型级状态
• type-strong-typing-strings - 用强类型替代字符串类型 API
• type-builder-required-fields - 对必填字段使用类型状态构建器

2. 所有权与借用（严重）

• own-prefer-borrowing - 参数优先使用借用而非所有权
• own-cow-conditional-clone - 使用 Cow 实现条件所有权
• own-accept-borrowed-types - 优先接受借用类型，而非拥有所有权的引用
• own-return-owned-for-flexibility - 返回拥有所有权的类型，为调用方提供灵活性
• own-avoid-unnecessary-clone - 避免不必要的 clone 调用
• own-lifetime-elision - 利用生命周期省略规则

3. 错误处理模式（高）

• err-use-result-not-panic - 对可恢复错误使用 Result，而非 panic!
• err-thiserror-for-libraries - 库的错误类型使用 thiserror
• err-anyhow-for-applications - 应用程序错误处理使用 anyhow
• err-question-mark-propagation - 使用问号运算符传播错误
• err-option-for-absence - 对缺失情况使用 Option，而非哨兵值

4. API 设计与 Trait（高）

• api-derive-common-traits - 为公共类型派生常见 Trait
• api-impl-standard-traits - 实现标准 Trait，打造易用的 API
• api-generic-bounds - 使用 Trait 约束提升泛型灵活性
• api-sealed-traits - 使用密封 Trait，防止外部实现
• api-builder-pattern - 复杂构造使用构建器模式
• api-extension-traits - 使用扩展 Trait 为外部类型添加方法

5. 模块与可见性（中高）

• mod-minimize-pub-api - 尽量缩小公共 API 的范围
• mod-pub-use-reexports - 使用 pub use 实现简洁的模块重新导出
• mod-split-large-modules - 将大型模块拆分为子模块
• mod-crate-prefix-imports - 内部导入使用 crate:: 前缀
• mod-tests-submodule - 使用 tests 子模块编写单元测试

6. 转换 Trait（中）

• conv-impl-from-not-into - 实现 From，而不是 Into
• conv-asref-for-flexibility - 接受 AsRef，以灵活处理字符串参数
• conv-impl-deref-for-newtypes - 实现 Deref，以透明访问新类型
• conv-tryfrom-for-fallible - 对可能失败的转换使用 TryFrom
• conv-inner-function-pattern - 使用内部函数模式减少单态化

7. 惯用模式（中）

• idiom-default-trait - 无参时实现 Default，而不是 new()
• idiom-constructor-naming - 遵循构造函数命名约定
• idiom-let-else - 模式匹配失败时使用 let-else 提前返回
• idiom-struct-update-syntax - 使用结构体更新语法进行部分覆盖
• idiom-destructuring-assignment - 使用解构处理多个返回值和字段访问
• idiom-match-guards - 使用 match 守卫处理复杂条件

8. 迭代器与集合（低中）

• iter-prefer-iterators-over-loops - 优先使用迭代器方法，而非手动循环
• iter-use-collect-turbofish - 使用 turbofish 显式指定 collect 类型
• iter-filter-map-combined - 使用 filter_map 合并过滤和转换
• iter-avoid-collect-then-iterate - 避免先收集再迭代
• iter-enumerate-for-indices - 使用 enumerate，而非手动跟踪索引

如何使用

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 分类结构和影响级别
• 规则模板 - 添加新规则的模板

完整编译文档

如需查看单文件的完整指南，请参阅 AGENTS.md。