rust-systems

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rust Systems Programming Best Practices

Rust系统编程最佳实践

Comprehensive Rust patterns and style conventions for systems programming, containing 52 rules across 5 categories. Designed for systems programming, CLI tools, and performance-critical applications.

一套全面的系统编程Rust模式与风格规范，包含5个类别下的52条规则。适用于系统编程、CLI工具和性能关键型应用场景。

When to Apply

适用场景

Reference these guidelines when:

Writing new Rust code or modules
Organizing Rust project structure
Defining custom types, traits, or error handling
Reviewing Rust code for style consistency
Building systems tools, CLIs, or daemon processes

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

编写新的Rust代码或模块
组织Rust项目结构
定义自定义类型、trait或错误处理逻辑
评审Rust代码以保证风格一致性
构建系统工具、CLI或守护进程

Rule Categories by Priority

按优先级划分的规则类别


org-
mod-
name-
type-
err-

Priority	Category	Impact	Prefix
1	Project Organization	HIGH	`org-`
2	Module Structure	HIGH	`mod-`
3	Naming Conventions	HIGH	`name-`
4	Type & Trait Patterns	HIGH	`type-`
5	Error Handling	HIGH	`err-`


org-
mod-
name-
type-
err-

优先级	类别	影响程度	前缀
1	项目组织	高	`org-`
2	模块结构	高	`mod-`
3	命名规范	高	`name-`
4	类型与Trait模式	高	`type-`
5	错误处理	高	`err-`

Quick Reference

快速参考

1. Project Organization (HIGH)

1. 项目组织（高优先级）

```
org-cargo-workspace
```
- Use Cargo Workspace for Multi-Crate Projects
```
org-directory-naming
```
- Use snake_case for All Directory Names
```
org-binary-library-separation
```
- Separate Binary and Library Crates
```
org-feature-domain-grouping
```
- Group Crates by Feature Domain
```
org-common-crate
```
- Use Dedicated Common Crate for Shared Utilities
```
org-flat-crate-structure
```
- Keep Crate Structure Flat

```
org-cargo-workspace
```
- 为多crate项目使用Cargo Workspace
```
org-directory-naming
```
- 所有目录名称使用snake_case
```
org-binary-library-separation
```
- 分离二进制与库Crate
```
org-feature-domain-grouping
```
- 按功能领域分组Crate
```
org-common-crate
```
- 使用专用公共Crate存放共享工具
```
org-flat-crate-structure
```
- 保持Crate结构扁平化

2. Module Structure (HIGH)

2. 模块结构（高优先级）

```
mod-explicit-declarations
```
- Use Explicit Module Declarations in lib.rs
```
mod-colocated-tests
```
- Co-locate Tests as test.rs Files
```
mod-submodule-organization
```
- Use mod.rs for Multi-File Modules
```
mod-types-errors-files
```
- Separate Types and Errors into Dedicated Files
```
mod-reexport-pattern
```
- Use pub use for Clean API Re-exports
```
mod-conditional-compilation
```
- Use cfg Attributes for Conditional Modules

```
mod-explicit-declarations
```
- 在lib.rs中使用显式模块声明
```
mod-colocated-tests
```
- 将测试代码放在同名test.rs文件中
```
mod-submodule-organization
```
- 为多文件模块使用mod.rs
```
mod-types-errors-files
```
- 将类型与错误分离到专用文件中
```
mod-reexport-pattern
```
- 使用pub use实现清晰的API重导出
```
mod-conditional-compilation
```
- 使用cfg属性实现条件编译模块

3. Naming Conventions (HIGH)

3. 命名规范（高优先级）

```
name-function-snake-case
```
- Use snake_case for Functions and Methods
```
name-type-pascal-case
```
- Use PascalCase for Types
```
name-constant-screaming
```
- Use SCREAMING_SNAKE_CASE for Constants
```
name-getter-prefix
```
- Prefix Getter Functions with get_
```
name-boolean-predicates
```
- Use is_, has_, should_ for Boolean Predicates
```
name-constructor-new
```
- Use new for Constructors
```
name-conversion-to-from
```
- Use to_ and from_ for Conversions
```
name-type-suffixes
```
- Use Descriptive Suffixes for Type Specialization
```
name-field-unit-suffixes
```
- Include Unit Suffixes in Field Names
```
name-module-snake-case
```
- Use snake_case for Module Names
```
name-generic-parameters
```
- Use Descriptive or Single-Letter Generic Parameters
```
name-lifetime-parameters
```
- Use Single Lowercase Letters for Lifetimes
```
name-test-files
```
- Name Test Files as test.rs

```
name-function-snake-case
```
- 函数与方法使用snake_case
```
name-type-pascal-case
```
- 类型使用PascalCase
```
name-constant-screaming
```
- 常量使用SCREAMING_SNAKE_CASE
```
name-getter-prefix
```
- Getter函数前缀使用get_
```
name-boolean-predicates
```
- 布尔断言使用is_、has_、should_前缀
```
name-constructor-new
```
- 构造函数使用new命名
```
name-conversion-to-from
```
- 转换函数使用to_和from_前缀
```
name-type-suffixes
```
- 为专用类型使用描述性后缀
```
name-field-unit-suffixes
```
- 字段名称中包含单位后缀
```
name-module-snake-case
```
- 模块名称使用snake_case
```
name-generic-parameters
```
- 泛型参数使用描述性名称或单字母
```
name-lifetime-parameters
```
- 生命周期参数使用单个小写字母
```
name-test-files
```
- 测试文件命名为test.rs

4. Type & Trait Patterns (HIGH)

4. 类型与Trait模式（高优先级）

```
type-option-nullable-fields
```
- Use Option<T> for Nullable Fields
```
type-standard-derives
```
- Use Consistent Derive Order for Data Structs
```
type-builder-pattern
```
- Use Builder Pattern with Method Chaining
```
type-associated-types
```
- Use Associated Types for Related Type Relationships
```
type-phantom-data
```
- Use PhantomData for Unused Generic Parameters
```
type-newtype-pattern
```
- Use Newtype Pattern for Type Safety
```
type-enum-copy-simple
```
- Derive Copy for Simple Enums
```
type-enum-variants
```
- Use Enums for Type-Safe Variants
```
type-trait-impl-grouping
```
- Group Related Trait Implementations Together
```
type-bitflags
```
- Use bitflags! for Type-Safe Bit Flags
```
type-operator-overload
```
- Implement Operator Traits for Domain Types
```
type-public-fields
```
- Use Public Fields for Data Structs
```
type-async-trait
```
- Use async_trait for Async Trait Methods
```
type-boxed-trait-objects
```
- Use Box<dyn Trait> for Runtime Polymorphism
```
type-type-aliases
```
- Use Type Aliases for Complex Generics

```
type-option-nullable-fields
```
- 可为空字段使用Option<T>
```
type-standard-derives
```
- 数据结构体使用一致的Derive顺序
```
type-builder-pattern
```
- 使用带方法链的构建器模式
```
type-associated-types
```
- 为相关类型关系使用关联类型
```
type-phantom-data
```
- 为未使用的泛型参数使用PhantomData
```
type-newtype-pattern
```
- 使用Newtype模式保证类型安全
```
type-enum-copy-simple
```
- 为简单枚举派生Copy trait
```
type-enum-variants
```
- 使用枚举实现类型安全的变体
```
type-trait-impl-grouping
```
- 将相关Trait实现分组存放
```
type-bitflags
```
- 使用bitflags!实现类型安全的位标志
```
type-operator-overload
```
- 为领域类型实现操作符Trait
```
type-public-fields
```
- 数据结构体使用公共字段
```
type-async-trait
```
- 为异步Trait方法使用async_trait
```
type-boxed-trait-objects
```
- 使用Box<dyn Trait>实现运行时多态
```
type-type-aliases
```
- 使用类型别名简化复杂泛型

5. Error Handling (HIGH)

5. 错误处理（高优先级）

```
err-thiserror-enum
```
- Use thiserror for Custom Error Types
```
err-result-alias
```
- Define Module-Local Result Type Alias
```
err-path-context
```
- Include Path Context in IO Errors
```
err-anyhow-context
```
- Use context() and with_context() for Error Messages
```
err-bail-validation
```
- Use bail! for Validation Failures
```
err-graceful-degradation
```
- Use Graceful Degradation for Non-Critical Operations
```
err-panic-unrecoverable
```
- Reserve panic! for Unrecoverable Situations
```
err-expect-message
```
- Use expect() with Descriptive Messages
```
err-source-attribute
```
- Use #[source] for Error Chaining
```
err-ok-or-else
```
- Use ok_or_else for Expensive Error Construction
```
err-two-tier-strategy
```
- Use Two-Tier Error Strategy

```
err-thiserror-enum
```
- 使用thiserror定义自定义错误类型
```
err-result-alias
```
- 定义模块本地的Result类型别名
```
err-path-context
```
- 在IO错误中包含路径上下文
```
err-anyhow-context
```
- 使用context()和with_context()添加错误信息
```
err-bail-validation
```
- 使用bail!处理验证失败
```
err-graceful-degradation
```
- 非关键操作使用优雅降级策略
```
err-panic-unrecoverable
```
- 仅在不可恢复场景下使用panic!
```
err-expect-message
```
- 使用expect()并添加描述性信息
```
err-source-attribute
```
- 使用#[source]实现错误链
```
err-ok-or-else
```
- 使用ok_or_else处理开销较大的错误构造
```
err-two-tier-strategy
```
- 使用双层错误处理策略

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 the complete guide with all rules expanded: AGENTS.md

如需查看包含所有规则扩展说明的完整指南：AGENTS.md