从入门到精通：Rust 错误处理完全指南

Rust 以“安全”为核心设计理念，其错误处理机制是保障内存安全和逻辑正确性的关键。与许多语言通过异常（Exception）隐式处理错误不同，Rust 采用显式错误返回的方式，强制开发者直面错误，从根本上避免了未捕获异常导致的程序崩溃或未定义行为。本文将带你从基础概念到高级模式，彻底掌握 Rust 错误处理。

一、错误的本质：可恢复 vs 不可恢复

Rust 将错误分为两大类，对应不同的处理策略：

1.1 不可恢复错误：`panic!`

当程序遇到无法继续执行的严重错误（如数组越界、断言失败、空指针解引用等）时，Rust 会触发 panic!，导致程序立即终止并打印错误信息。

触发场景：

显式调用 panic! 宏： fn main() { panic!("发生不可恢复的错误！"); // 输出：thread 'main' panicked at '发生不可恢复的错误！', src/main.rs:2:5 }
隐式触发：如访问超出数组长度的索引（arr[10] 但 arr 长度为 5）、解引用 Option::None 的 unwrap() 等。

`panic!` 的行为：

默认展开栈（unwind）：清理资源（调用析构函数）后退出；
可通过编译选项 panic = 'abort' 直接终止程序（适合嵌入式场景，减少二进制体积）。

何时使用 `panic!`？

原型开发：快速验证逻辑时用 unwrap()/expect() 简化代码（生产环境需替换）；
不可恢复的逻辑错误：如配置文件格式错误导致程序无法启动（此时应终止而非继续运行）；
内部 bug：如函数前置条件被破坏（assert!(x > 0) 失败时）。

1.2 可恢复错误：`Result<T, E>`

大多数错误是可恢复的（如文件不存在、网络请求失败、用户输入无效等），此时应使用 Result<T, E> 枚举显式返回错误，让调用者决定如何处理（重试、降级、提示用户等）。

二、可恢复错误核心：`Result<T, E>` 详解

Result<T, E> 是 Rust 处理可恢复错误的基石，定义为：

enum Result<T, E> {
    Ok(T),   // 成功时包含结果值 T
    Err(E),  // 失败时包含错误类型 E
}

2.1 基本用法：匹配与处理

示例：读取文件内容

use std::fs::File;
use std::io::Read;

fn read_file(path: &str) -> Result<String, std::io::Error> {
    let mut file = File::open(path)?; // 若打开失败，返回 Err；否则继续执行
    let mut content = String::new();
    file.read_to_string(&mut content)?; // 若读取失败，返回 Err
    Ok(content) // 成功则返回 Ok(content)
}

fn main() {
    match read_file("hello.txt") {
        Ok(content) => println!("文件内容：{}", content),
        Err(e) => println!("读取失败：{}", e), // 打印错误（如 "No such file or directory"）
    }
}

2.2 处理 `Result` 的常用方法

（1）`match`：最显式的模式匹配

match 强制覆盖所有可能分支（Ok 和 Err），避免遗漏错误：

let result: Result<i32, &str> = Ok(42);
match result {
    Ok(num) => println!("结果是：{}", num), // 输出：42
    Err(err) => println!("错误：{}", err),
}

（2）`unwrap()` 与 `expect()`：快速获取值（慎用！）

unwrap()：若 Result 为 Ok，返回内部值；若为 Err，触发 panic!。 let x: Result<i32, &str> = Ok(10); println!("{}", x.unwrap()); // 输出：10 let y: Result<i32, &str> = Err("出错了"); y.unwrap(); // 触发 panic!
expect(msg)：与 unwrap() 类似，但可自定义 panic 信息，便于调试： let y: Result<i32, &str> = Err("出错了"); y.expect("读取配置文件失败"); // panic 信息："读取配置文件失败: "出错了""

注意：仅在**确定 Result 必为 Ok** 时使用（如测试代码），生产环境禁用，否则可能导致意外崩溃。

（3）`?` 操作符：错误传播的“语法糖”

? 是 Rust 1.13 引入的语法糖，用于简化错误传播：若 Result 为 Ok，则提取 T 并继续执行；若为 Err，则立即返回该 Err（需函数返回 Result 或 Option）。

原理：等价于 match res { Ok(v) => v, Err(e) => return Err(e.into()) }（into() 用于类型转换，需实现 From<E> trait）。

示例：用 ? 简化文件读取

use std::fs::File;
use std::io::Read;

fn read_file(path: &str) -> Result<String, std::io::Error> {
    let mut file = File::open(path)?; // 出错则返回 Err
    let mut content = String::new();
    file.read_to_string(&mut content)?; // 同上
    Ok(content)
}

**? 的类型转换**：若 ? 后的 Err 类型与目标返回类型 E 不同，需实现 From<E> trait 自动转换：

#[derive(Debug)]
struct AppError(String);

impl From<std::num::ParseIntError> for AppError {
    fn from(e: std::num::ParseIntError) -> Self {
        AppError(format!("解析整数失败：{}", e))
    }
}

fn parse_str(s: &str) -> Result<i32, AppError> {
    let num = s.parse()?; // ParseIntError 自动转换为 AppError
    Ok(num)
}

（4）`map` 与 `and_then`：函数式组合操作

map：对 Ok(T) 中的 T 进行转换，保持 Result 结构不变；Err 分支直接透传： let res: Result<i32, &str> = Ok(5); let doubled = res.map(|x| x * 2); // Ok(10)
and_then：转换函数返回 Result，用于链式执行多个可能失败的操作： fn parse_and_double(s: &str) -> Result<i32, std::num::ParseIntError> { s.parse().and_then(|x| Ok(x * 2)) // 先解析，再翻倍（任一失败返回 Err） }

三、标准库错误体系：`std::error::Error` trait

直接使用 String 或 &str 作为错误类型缺乏结构化信息和统一接口。Rust 标准库提供 std::error::Error trait 作为所有错误类型的“基类”，定义了错误的基本行为。

3.1 `Error` trait 的核心方法

pub trait Error: Debug + Display {
    // 返回错误的简短描述（如 "file not found"）
    fn description(&self) -> &str { ... }
    // 返回错误的详细原因（如 "permission denied"）
    fn cause(&self) -> Option<&dyn Error> { ... } // Rust 1.33+ 推荐用 source()
    // 返回错误的根源（替代 cause()）
    fn source(&self) -> Option<&(dyn Error + 'static)> { ... }
}

**Display**：用于打印错误信息（用户可见）；
**Debug**：用于调试（开发者可见，需 #[derive(Debug)]）；
**source()**：返回错误的“根源”（如 ParseIntError 是 AppError 的根源）。

3.2 标准库错误类型示例

**std::io::Error**：I/O 操作错误（如文件不存在、网络断开）；
**std::num::ParseIntError**：字符串解析为整数失败；
**Box<dyn Error>**：动态分发错误（“错误 trait 对象”），可容纳任意实现 Error 的类型（常用于函数返回多种错误）。

四、自定义错误类型：从简单到复杂

实际开发中，需根据需求定义结构化错误类型，平衡信息丰富度和使用便捷性。

4.1 基础版：枚举错误（适合少量错误类型）

用枚举定义不同错误变体，实现 Error 和 Display：

#[derive(Debug, PartialEq)]
enum MyError {
    NotFound,       // 资源不存在
    PermissionDenied, // 权限不足
    InvalidInput(String), // 输入无效（携带上下文）
}

// 实现 Display（用户可见的错误信息）
impl std::fmt::Display for MyError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            MyError::NotFound => write!(f, "资源未找到"),
            MyError::PermissionDenied => write!(f, "权限不足"),
            MyError::InvalidInput(msg) => write!(f, "无效输入：{}", msg),
        }
    }
}

// 实现 Error（空实现即可，因 Error 继承自 Debug 和 Display）
impl std::error::Error for MyError {}

// 使用示例
fn read_config() -> Result<String, MyError> {
    if !std::path::Path::new("config.txt").exists() {
        return Err(MyError::NotFound);
    }
    Ok("配置内容".to_string())
}

4.2 进阶版：结构体错误（适合携带详细上下文）

用结构体携带错误码、消息、根源错误等信息：

use std::time::SystemTime;

#[derive(Debug)]
struct AppError {
    code: u32,          // 错误码
    message: String,    // 错误消息
    source: Option<Box<dyn std::error::Error + 'static>>, // 根源错误
    timestamp: SystemTime, // 时间戳
}

impl AppError {
    fn new(code: u32, message: &str, source: Option<Box<dyn std::error::Error>>) -> Self {
        Self {
            code,
            message: message.to_string(),
            source,
            timestamp: SystemTime::now(),
        }
    }
}

// 实现 Display
impl std::fmt::Display for AppError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "[{}] {} (timestamp: {:?})", self.code, self.message, self.timestamp)?;
        if let Some(source) = &self.source {
            write!(f, "\n根源错误：{}", source)?;
        }
        Ok(())
    }
}

// 实现 Error
impl std::error::Error for AppError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        self.source.as_deref()
    }
}

// 使用示例
fn parse_data(data: &str) -> Result<i32, AppError> {
    data.parse().map_err(|e| {
        AppError::new(1001, "解析数据失败", Some(Box::new(e)))
    })
}

4.3 集成第三方库：`thiserror` 与 `anyhow`

手动实现错误类型较繁琐，可借助第三方库简化：

（1）`thiserror`：派生宏自动实现 `Error`

thiserror 通过 #[derive(thiserror::Error)] 自动实现 Error、Display 等 trait，适合库开发（需精确控制错误类型）。

示例：

use thiserror::Error;

#[derive(Error, Debug, PartialEq)]
enum MyError {
    #[error("资源未找到")]
    NotFound,
    #[error("权限不足")]
    PermissionDenied,
    #[error("无效输入：{0}")]
    InvalidInput(String), // 带参数的错误消息
}

// 无需手动实现 Display 和 Error，直接用！
fn read_config() -> Result<String, MyError> {
    Err(MyError::NotFound)
}

（2）`anyhow`：动态错误（适合应用开发）

anyhow 提供 anyhow::Error 类型，可容纳任意错误，并自动管理上下文（如 context()、with_context()），适合应用开发（快速迭代，无需定义大量错误类型）。

示例：

use anyhow::{Context, Result};

fn read_file(path: &str) -> Result<String> {
    let content = std::fs::read_to_string(path)
        .with_context(|| format!("读取文件失败：{}", path))?; // 添加上下文
    Ok(content)
}

fn main() -> Result<()> {
    let content = read_file("hello.txt")
        .context("启动失败：无法读取配置文件")?; // 更高层上下文
    println!("{}", content);
    Ok(())
}