sing-rust 🦀

Rust 全特性速查学习项目 — 深入浅出，温故知新

一个覆盖 Rust 语言所有重要特性的学习参考项目。代码简练、注释丰富（中英混合），可编译运行，适合快速查阅和复习。

特性覆盖

模块	主题	核心内容
basics	变量、类型、控制流	let/mut/shadowing、标量&复合类型、match/if let/let-else
ownership	所有权、借用、生命周期	move/Copy/Clone、&T/&mut T、lifetime 'a/'static、HRTB
structs_enums	结构体、枚举、模式匹配	struct variants、#[derive]、match guard、@绑定、#[non_exhaustive]
traits_generics	Trait 与泛型	impl Trait/dyn Trait、关联类型、运算符重载、const generics、PhantomData
error_handling	错误处理	Option/Result 组合子、? 运算符、自定义错误、Box<dyn Error>
collections_iterators	集合、迭代器、闭包	Vec/HashMap/BTreeMap、Iterator 适配器、Fn/FnMut/FnOnce
smart_pointers	智能指针	Box/Rc/Arc/RefCell/Weak/Cow/Pin
concurrency	并发编程	thread/Mutex/RwLock/mpsc/Atomic/scoped threads
async_await	异步编程	async/.await/tokio/select!/async trait
macros	宏	macro_rules!、fragment specifiers、内置宏、过程宏概念
unsafe_rust	Unsafe Rust	裸指针、unsafe fn/unsafe trait、FFI、union
type_system	高级类型系统	类型别名、newtype、!/DST/ZST、GATs、type-state pattern
strings_io	字符串与 I/O	String/&str/UTF-8、Path/PathBuf、文件读写
testing_demo	测试	#[test]/#[should_panic]/#[ignore]/doc test

快速开始

# 克隆项目
git clone <repo-url>
cd sing-rust

# 运行所有演示
cargo run

# 运行测试
cargo test

# 生成文档
cargo doc --open

项目结构

sing-rust/
├── Cargo.toml              # 项目配置
├── README.md               # 本文件
└── src/
    ├── main.rs             # 入口：调用所有模块的 demo()
    ├── lib.rs              # 模块声明、可见性、条件编译演示
    ├── basics.rs           # 1. 变量、类型、控制流
    ├── ownership.rs        # 2. 所有权、借用、生命周期
    ├── structs_enums.rs    # 3. 结构体、枚举、模式匹配
    ├── traits_generics.rs  # 4. Trait、泛型、标准 Trait
    ├── error_handling.rs   # 5. 错误处理
    ├── collections_iterators.rs  # 6. 集合、迭代器、闭包
    ├── smart_pointers.rs   # 7. 智能指针
    ├── concurrency.rs      # 8. 并发编程
    ├── async_await.rs      # 9. 异步编程
    ├── macros.rs           # 10. 宏
    ├── unsafe_rust.rs      # 11. Unsafe Rust
    ├── type_system.rs      # 12. 高级类型系统
    ├── strings_io.rs       # 13. 字符串与 I/O
    └── testing_demo.rs     # 14. 测试

使用方式

运行演示

cargo run

输出所有模块的演示结果，每个模块用分隔线标注，方便查看特定主题。

运行测试

cargo test                     # 运行所有测试
cargo test test_add            # 运行名称匹配的测试
cargo test -- --ignored        # 运行 #[ignore] 标记的测试
cargo test -- --show-output    # 显示测试中的 println 输出
cargo test --doc               # 只运行 doc tests

查看文档

cargo doc --open

生成 HTML 文档，包含所有模块的文档注释和代码示例。

学习建议

1. 按模块学习：每个 .rs 文件对应一个主题，可以单独阅读
2. 看注释：代码中有详细的中英混合注释，解释每个特性
3. 运行观察：cargo run 查看输出，结合代码理解执行流程
4. 动手修改：尝试修改代码，观察编译错误，加深理解
5. 查阅文档：cargo doc --open 查看生成的文档

特性速查

所有权三规则

// 1. 每个值有且只有一个 owner
// 2. 同一时刻只能有一个 owner
// 3. owner 离开作用域时，值被 drop

借用规则

// 同一时刻：要么有多个 &T，要么有一个 &mut T（互斥）
// 引用必须始终有效（no dangling references）

生命周期省略规则

// 1. 每个引用参数获得独立的生命周期
// 2. 只有一个输入生命周期参数时，它赋给所有输出
// 3. 方法中 &self/&mut self 的生命周期赋给所有输出

闭包 Trait

// Fn     — 不可变借用捕获的变量（可多次调用）
// FnMut  — 可变借用捕获的变量
// FnOnce — 消费捕获的变量（只能调用一次）

智能指针选择

// Box<T>      — 堆分配，单一所有权
// Rc<T>       — 引用计数，多所有权（单线程）
// Arc<T>      — 原子引用计数（多线程）
// RefCell<T>  — 运行时借用检查，内部可变性
// Mutex<T>    — 互斥锁（多线程内部可变性）

Marker Traits

// Send  — 类型可以安全地在线程间转移所有权
// Sync  — 类型可以安全地在线程间共享引用
// Sized — 编译期已知大小（默认 bound）
// Copy  — 按位复制而非 move

依赖

• Rust Edition 2021
• tokio — 异步运行时（用于 async/await 演示）

许可证

MIT

---

"The Rust programming language helps you write faster, more reliable software."