rust-idioms

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rust Community Rust Refactoring Best Practices

Rust社区Rust重构最佳实践

Comprehensive refactoring and idiomatic patterns guide for Rust applications, maintained by the Rust Community. Contains 44 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

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

When to Apply

适用场景

Reference these guidelines when:

Writing new Rust code with strong type guarantees
Refactoring ownership and borrowing patterns
Designing error handling strategies
Creating public APIs with traits and generics
Organizing modules and controlling visibility

在以下场景中可参考本指南：

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

Rule Categories by Priority

按优先级划分的规则类别


type-
own-
err-
api-
mod-
conv-
idiom-
iter-

Priority	Category	Impact	Prefix
1	Type Safety & Newtype Patterns	CRITICAL	`type-`
2	Ownership & Borrowing	CRITICAL	`own-`
3	Error Handling Patterns	HIGH	`err-`
4	API Design & Traits	HIGH	`api-`
5	Module & Visibility	MEDIUM-HIGH	`mod-`
6	Conversion Traits	MEDIUM	`conv-`
7	Idiomatic Patterns	MEDIUM	`idiom-`
8	Iterator & Collections	LOW-MEDIUM	`iter-`


type-
own-
err-
api-
mod-
conv-
idiom-
iter-

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

Quick Reference

快速参考

1. Type Safety & Newtype Patterns (CRITICAL)

1. 类型安全与Newtype模式（关键）

```
type-newtype-units
```
- Use newtype pattern for unit safety
```
type-newtype-invariants
```
- Encode invariants in newtype constructors
```
type-non-exhaustive-enums
```
- Use non-exhaustive for extensible enums
```
type-phantom-data
```
- Use PhantomData for type-level state
```
type-strong-typing-strings
```
- Replace stringly-typed APIs with strong types
```
type-builder-required-fields
```
- Use typestate builders for required fields

```
type-newtype-units
```
- 使用Newtype模式保证单元安全
```
type-newtype-invariants
```
- 在Newtype构造函数中编码不变量
```
type-non-exhaustive-enums
```
- 对可扩展枚举使用non-exhaustive
```
type-phantom-data
```
- 使用PhantomData实现类型级状态
```
type-strong-typing-strings
```
- 用强类型替换字符串类型的API
```
type-builder-required-fields
```
- 使用类型状态构建器处理必填字段

2. Ownership & Borrowing (CRITICAL)

2. 所有权与借用（关键）

```
own-prefer-borrowing
```
- Prefer borrowing over ownership in parameters
```
own-cow-conditional-clone
```
- Use Cow for conditional ownership
```
own-accept-borrowed-types
```
- Accept borrowed types over owned references
```
own-return-owned-for-flexibility
```
- Return owned types for caller flexibility
```
own-avoid-unnecessary-clone
```
- Avoid unnecessary clone calls
```
own-lifetime-elision
```
- Leverage lifetime elision rules

```
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. Error Handling Patterns (HIGH)

3. 错误处理模式（高）

```
err-use-result-not-panic
```
- Use Result instead of panic! for recoverable errors
```
err-thiserror-for-libraries
```
- Use thiserror for library error types
```
err-anyhow-for-applications
```
- Use anyhow for application error handling
```
err-question-mark-propagation
```
- Use the question mark operator for error propagation
```
err-option-for-absence
```
- Use Option for absence, not sentinel values

```
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 Design & Traits (HIGH)

4. API设计与Trait（高）

```
api-derive-common-traits
```
- Derive common traits for public types
```
api-impl-standard-traits
```
- Implement standard traits for ergonomic APIs
```
api-generic-bounds
```
- Use trait bounds for generic flexibility
```
api-sealed-traits
```
- Use sealed traits to prevent external implementation
```
api-builder-pattern
```
- Use builder pattern for complex construction
```
api-extension-traits
```
- Use extension traits to add methods to foreign types

```
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. Module & Visibility (MEDIUM-HIGH)

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

```
mod-minimize-pub-api
```
- Minimize public API surface
```
mod-pub-use-reexports
```
- Use pub use for clean module re-exports
```
mod-split-large-modules
```
- Split large modules into submodules
```
mod-crate-prefix-imports
```
- Use crate:: prefix for internal imports
```
mod-tests-submodule
```
- Use tests submodule for unit tests

```
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. Conversion Traits (MEDIUM)

6. 转换Trait（中）

```
conv-impl-from-not-into
```
- Implement From instead of Into
```
conv-asref-for-flexibility
```
- Accept AsRef for flexible string parameters
```
conv-impl-deref-for-newtypes
```
- Implement Deref for transparent newtype access
```
conv-tryfrom-for-fallible
```
- Use TryFrom for fallible conversions
```
conv-inner-function-pattern
```
- Use inner function pattern to reduce monomorphization

```
conv-impl-from-not-into
```
- 实现From而非Into
```
conv-asref-for-flexibility
```
- 接受AsRef以提升字符串参数灵活性
```
conv-impl-deref-for-newtypes
```
- 为透明Newtype实现Deref以方便访问
```
conv-tryfrom-for-fallible
```
- 使用TryFrom处理可失败的转换
```
conv-inner-function-pattern
```
- 使用内部函数模式减少单态化

7. Idiomatic Patterns (MEDIUM)

7. 惯用模式（中）

```
idiom-default-trait
```
- Implement Default instead of new() without arguments
```
idiom-constructor-naming
```
- Follow constructor naming conventions
```
idiom-let-else
```
- Use let-else for early returns on pattern match failure
```
idiom-struct-update-syntax
```
- Use struct update syntax for partial overrides
```
idiom-destructuring-assignment
```
- Use destructuring for multiple returns and field access
```
idiom-match-guards
```
- Use match guards for complex conditions

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

8. Iterator & Collections (LOW-MEDIUM)

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

```
iter-prefer-iterators-over-loops
```
- Prefer iterator methods over manual loops
```
iter-use-collect-turbofish
```
- Use turbofish for explicit collect type
```
iter-filter-map-combined
```
- Use filter_map for combined filter and transform
```
iter-avoid-collect-then-iterate
```
- Avoid collecting then iterating
```
iter-enumerate-for-indices
```
- Use enumerate instead of manual index tracking

```
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而非手动跟踪索引

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明与代码示例：

章节定义 - 类别结构与影响等级说明
规则模板 - 添加新规则的模板

Full Compiled Document

完整编译文档

For a single-file comprehensive guide, see AGENTS.md.

如需单文件版的全面指南，请查看AGENTS.md。