docs(cheatsheet): 添加Rust错误处理速查表文档

新增Rust错误处理速查表文档，涵盖Option/Result使用、thiserror和anyhow库的最佳实践，以及错误处理的核心概念和场景选择指南

Author: mudssky

docs/cheatsheet/rust/错误处理.md

@@ -0,0 +1,205 @@
+
+## Rust 错误处理速查表 (Cheatsheet)
+
+### 核心理念
+
+Rust 通过在类型系统中显式表达错误，强制开发者处理潜在的失败情况，从而构建出高可靠性的软件。核心思想是区分**可恢复的错误 (Recoverable Errors)** 和 **不可恢复的错误 (Unrecoverable Errors)**。
+
+| 类别 | 描述 | 主要工具 |
+| :--- | :--- | :--- |
+| **可恢复错误** | 预料之中的、可以被合理处理的错误（如文件未找到、网络中断）。 | `Result<T, E>` |
+| **不可恢复错误** | 意料之外的、代表程序缺陷的错误（如数组越界访问）。 | `panic!` |
+
+---
+
+### 1. Rust 内置错误处理机制
+
+#### `Option<T>`：处理“值可能不存在”的情况
+
+用于表示一个值可能是 `Some(value)` 或 `None`（空）。
+
+* **定义**：`enum Option<T> { Some(T), None }`
+* **常用方法**：
+  * `unwrap()`：获取 `Some` 里的值，但如果为 `None` 则会 `panic!`。**慎用！**
+  * `expect("message")`：与 `unwrap()` 类似，但在 `panic!` 时提供自定义消息。
+  * `unwrap_or(default_value)`：如果为 `None`，则返回一个默认值。
+  * `is_some()` / `is_none()`：检查是否包含值。
+  * `map(fn)` / `and_then(fn)`：对内部的值进行操作。
+
+```rust
+fn find_user(id: u32) -> Option<String> {
+    if id == 1 { Some("Alice".to_string()) } else { None }
+}
+
+let user = find_user(1).unwrap_or("Default User".to_string()); // "Alice"
+let user2 = find_user(2).unwrap_or("Default User".to_string()); // "Default User"
+```
+
+#### `Result<T, E>`：处理“操作可能失败”的情况
+
+用于表示一个操作的结果可能是 `Ok(value)`（成功）或 `Err(error)`（失败）。
+
+* **定义**：`enum Result<T, E> { Ok(T), Err(E) }`
+* **常用方法**：
+  * `unwrap()` / `expect("message")`：与 `Option` 类似，成功时返回值，失败时 `panic!`。
+  * `is_ok()` / `is_err()`：检查结果是成功还是失败。
+  * `ok()`：将 `Result<T, E>` 转换为 `Option<T>`。
+  * `err()`：将 `Result<T, E>` 转换为 `Option<E>`。
+  * `map_err(fn)`：在不改变 `Ok` 值的情况下，转换 `Err` 中的错误类型。
+
+```rust
+fn parse_number(s: &str) -> Result<i32, std::num::ParseIntError> {
+    s.parse::<i32>()
+}
+
+match parse_number("123") {
+    Ok(num) => println!("Success: {}", num),    // Success: 123
+    Err(e) => println!("Error: {}", e),
+}
+```
+
+#### `?` 操作符：优雅地传播错误
+
+`?` 是 Rust 错误处理的语法糖，用于简化错误传播。它只能用于返回 `Result` 或 `Option` 的函数。
+
+* **工作原理**：如果 `Result` 是 `Ok(T)`，它会解包出 `T`；如果是 `Err(E)`，它会立即从当前函数返回 `Err(E)`。
+* **前提**：当前函数的错误类型必须能通过 `From::from` trait 从 `?` 操作的错误类型转换而来。
+
+```rust
+// 旧方法 (手动 match)
+fn read_username_from_file_old() -> Result<String, std::io::Error> {
+    let mut f = match std::fs::File::open("username.txt") {
+        Ok(file) => file,
+        Err(e) => return Err(e),
+    };
+    let mut s = String::new();
+    match f.read_to_string(&mut s) {
+        Ok(_) => Ok(s),
+        Err(e) => Err(e),
+    }
+}
+
+// 新方法 (使用 ?)
+use std::io::{self, Read};
+fn read_username_from_file_new() -> Result<String, io::Error> {
+    let mut s = String::new();
+    // 如果 open 失败，? 会立即返回 Err
+    std::fs::File::open("username.txt")?.read_to_string(&mut s)?;
+    Ok(s)
+}
+```
+
+---
+
+### 2. `thiserror`：为你的库创建专业的错误类型
+
+**目标**：为库（library/crate）定义具体的、结构化的错误类型，方便库的使用者以编程方式处理它们。
+
+**安装**：`cargo add thiserror`
+
+**用法**：
+
+1. 创建一个 `pub enum Error`。
+2. 使用 `#[derive(Error, Debug)]`。
+3. 用 `#[error("...")]` 为每个变体定义错误信息。
+4. 用 `#[from]` 将底层错误自动转换为你的错误类型。
+
+**示例**：
+
+```rust
+// 在你的库代码中 (e.g., src/lib.rs)
+use thiserror::Error;
+
+// 1. 定义一个通用的 Result 别名
+pub type Result<T> = std::result::Result<T, DataError>;
+
+// 2. 定义你的自定义错误枚举
+#[derive(Error, Debug)]
+pub enum DataError {
+    #[error("数据库连接失败")]
+    DatabaseError(#[source] sqlx::Error), // `#[source]` 用于链接底层错误
+
+    #[error("I/O 错误: {0}")]
+    IoError(#[from] std::io::Error), // `#[from]` 让 `?` 自动转换 io::Error
+
+    #[error("找不到记录 ID: {id}")]
+    NotFound { id: String },
+
+    #[error("输入无效: {message}")]
+    InvalidInput { message: String },
+}
+
+// 3. 在函数中使用
+pub fn get_data(id: &str) -> Result<String> {
+    if id.is_empty() {
+        // 返回一个具体的错误变体
+        return Err(DataError::InvalidInput { message: "ID 不能为空".into() });
+    }
+    // `?` 会自动将 std::io::Error 转换为 DataError::IoError
+    let config = std::fs::read_to_string("config.txt")?;
+    
+    // ... 其他逻辑 ...
+    Err(DataError::NotFound { id: id.to_string() })
+}
+```
+
+---
+
+### 3. `anyhow`：简化应用程序的错误处理
+
+**目标**：在应用程序（binary）中，当你不太关心具体的错误类型，只想轻松地传播错误并添加上下文时使用。
+
+**安装**：`cargo add anyhow`
+
+**用法**：
+
+1. 在函数签名中使用 `anyhow::Result<T>`。
+2. `?` 可以作用于任何实现了 `std::error::Error` 的错误类型。
+3. 使用 `.context("...")` 或 `.with_context(|| ...)` 方法在错误传播链上添加上下文信息。
+
+**示例**：
+
+```rust
+// 在你的应用程序代码中 (e.g., src/main.rs)
+use anyhow::{Context, Result};
+
+// my_library 是上面用 thiserror 编写的库
+use my_library::DataError; 
+
+fn main() -> Result<()> {
+    // anyhow::Result 让我们可以在 main 函数中使用 ?
+    let data = load_user_data("user123")
+        .with_context(|| "无法加载用户数据")?;
+
+    println!("成功获取数据: {}", data);
+    Ok(())
+}
+
+fn load_user_data(id: &str) -> Result<String> {
+    // 调用库函数，? 会自动将 DataError 包装进 anyhow::Error
+    let data = my_library::get_data(id)
+        .context("从 my_library 获取数据失败")?;
+    
+    // ... 其他逻辑 ...
+    Ok(data)
+}
+
+// 当运行并出错时，anyhow 会打印出完整的错误链：
+// Error: 无法加载用户数据
+//
+// Caused by:
+//   0: 从 my_library 获取数据失败
+//   1: 找不到记录 ID: user123
+```
+
+---
+
+### 总结：何时使用什么？
+
+| 场景 | 推荐工具 | 为什么？ |
+| :--- | :--- | :--- |
+| **编写库 (Library)** | **`thiserror`** | 创建具体的、结构化的错误类型，让调用者可以 `match` 并从容处理。 |
+| **编写应用程序 (Application)** | **`anyhow`** | 简单！轻松包装任何错误，添加上下文，并打印出用户友好的报告。 |
+| **函数可能返回空值** | **`Option<T>`** | 这是“没有值”的语义，而不是“失败”。 |
+| **在函数间传播错误** | **`?` 操作符** | 保持代码简洁和可读。 |
+| **致命的程序缺陷** | **`panic!`** | 用于指示不可恢复的状态，例如违反了代码不变量。避免在库的公共 API 中使用。 |