Rust 错误处理完全指南：从 Result 到自定义错误类型

特性	可恢复错误	不可恢复错误
表示方式	`Result<T, E>` / `Option<T>`	`panic!`
处理方式	显式处理	终止程序
适用场景	预期的错误	程序逻辑错误
示例	文件不存在	内存安全违规

1.2 与其他语言对比

// Rust：显式错误处理
fn read_file(path: &str) -> Result<String, std::io::Error> {
    std::fs::read_to_string(path)
}

fn main() {
    match read_file("config.txt") {
        Ok(content) => println!("内容: {}", content),
        Err(e) => eprintln!("错误: {}", e),
    }
}

# Python：异常处理
def read_file(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError as e:
        print(f"错误: {e}")
        return None

// Java：受检异常
public String readFile(String path) throws IOException {
    return Files.readString(Paths.get(path));
}

二、Option 类型深度剖析

2.1 Option 基础

fn main() {
    let some_number = Some(5);
    let no_number: Option<i32> = None;
    
    // 模式匹配
    match some_number {
        Some(value) => println!("有值: {}", value),
        None => println!("无值"),
    }
    
    // 常用方法
    println!("是否有值: {}", some_number.is_some());
    println!("是否无值: {}", some_number.is_none());
    
    // unwrap（危险：None时会panic）
    // let value = no_number.unwrap();
    
    // unwrap_or：提供默认值
    let value = no_number.unwrap_or(0);
    println!("值或默认: {}", value);
    
    // unwrap_or_else：惰性计算默认值
    let value = no_number.unwrap_or_else(|| {
        println!("计算默认值");
        42
    });
    
    // expect：带自定义错误消息
    // let value = no_number.expect("期望有值");
}

2.2 Option 链式操作

fn main() {
    let numbers = vec![Some(1), Some(2), None, Some(4)];
    
    // map：转换内部值
    let doubled: Vec<Option<i32>> = numbers.iter()
        .map(|opt| opt.map(|n| n * 2))
        .collect();
    println!("加倍: {:?}", doubled);
    
    // and_then（flatMap）：链式操作
    fn square_if_even(n: i32) -> Option<i32> {
        if n % 2 == 0 {
            Some(n * n)
        } else {
            None
        }
    }
    
    let result = Some(4).and_then(square_if_even);
    println!("偶数平方: {:?}", result); // Some(16)
    
    let result = Some(3).and_then(square_if_even);
    println!("奇数平方: {:?}", result); // None
    
    // filter：条件过滤
    let value = Some(10).filter(|&x| x > 5);
    println!("过滤后: {:?}", value); // Some(10)
    
    // or：提供备选Option
    let backup = Some(3).or(Some(5));
    println!("备选: {:?}", backup); // Some(3)
    
    let backup = None.or(Some(5));
    println!("备选: {:?}", backup); // Some(5)
}

2.3 实战示例：安全的配置访问

use std::collections::HashMap;

#[derive(Debug)]
struct Config {
    settings: HashMap<String, String>,
}

impl Config {
    fn new() -> Self {
        let mut settings = HashMap::new();
        settings.insert("host".to_string(), "localhost".to_string());
        settings.insert("port".to_string(), "8080".to_string());
        Config { settings }
    }
    
    fn get(&self, key: &str) -> Option<&String> {
        self.settings.get(key)
    }
    
    fn get_or_default(&self, key: &str, default: &str) -> String {
        self.get(key)
            .map(|s| s.clone())
            .unwrap_or_else(|| default.to_string())
    }
    
    fn get_port(&self) -> Option<u16> {
        self.get("port")
            .and_then(|s| s.parse().ok())
    }
}

fn main() {
    let config = Config::new();
    
    println!("主机: {}", config.get_or_default("host", "0.0.0.0"));
    println!("调试: {}", config.get_or_default("debug", "false"));
    
    if let Some(port) = config.get_port() {
        println!("端口号: {}", port);
    }
}

三、Result 类型完全指南

3.1 Result 基础

use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file(path: &str) -> Result<String, io::Error> {
    let mut file = File::open(path)?;  // ? 运算符
    let mut username = String::new();
    file.read_to_string(&mut username)?;
    Ok(username)
}

fn main() {
    match read_username_from_file("username.txt") {
        Ok(username) => println!("用户名: {}", username),
        Err(e) => eprintln!("读取失败: {}", e),
    }
}

3.2 ? 运算符详解

工作原理：

// 使用 ? 运算符
fn function_with_question_mark() -> Result<(), std::io::Error> {
    let file = File::open("file.txt")?;
    Ok(())
}

// 等价于
fn function_expanded() -> Result<(), std::io::Error> {
    let file = match File::open("file.txt") {
        Ok(f) => f,
        Err(e) => return Err(e),
    };
    Ok(())
}

? 运算符的类型转换：

use std::error::Error;
use std::fs::File;
use std::io;

// ? 会自动调用 From trait 进行类型转换
fn read_file() -> Result<String, Box<dyn Error>> {
    let mut file = File::open("file.txt")?;  // io::Error
    let mut content = String::new();
    file.read_to_string(&mut content)?;      // io::Error
    Ok(content)
}

可视化流程：

graph TD
    A[执行表达式] --> B{Result?}
    B -->|Ok(value)| C[返回 value]
    B -->|Err(e)| D[提前返回 Err]
    
    C --> E[继续执行]
    D --> F[函数结束]

3.3 Result 方法链

fn main() {
    let result: Result<i32, &str> = Ok(10);
    
    // map：转换 Ok 值
    let doubled = result.map(|x| x * 2);
    println!("加倍: {:?}", doubled); // Ok(20)
    
    // map_err：转换错误
    let mapped_err = Err("error").map_err(|e| format!("错误: {}", e));
    println!("{:?}", mapped_err);
    
    // and_then：链式操作
    fn divide(a: i32, b: i32) -> Result<i32, String> {
        if b == 0 {
            Err("除数为零".to_string())
        } else {
            Ok(a / b)
        }
    }
    
    let result = Ok(10)
        .and_then(|x| divide(x, 2))
        .and_then(|x| divide(x, 0));
    println!("链式计算: {:?}", result); // Err
    
    // or_else：错误恢复
    let recovered = Err("first error")
        .or_else(|_| Err("second error"))
        .or(Ok(42));
    println!("恢复: {:?}", recovered); // Ok(42)
}

四、自定义错误类型

4.1 简单枚举错误

#[derive(Debug)]
enum MathError {
    DivisionByZero,
    NegativeSquareRoot,
    Overflow,
}

fn divide(a: f64, b: f64) -> Result<f64, MathError> {
    if b == 0.0 {
        Err(MathError::DivisionByZero)
    } else {
        Ok(a / b)
    }
}

fn sqrt(x: f64) -> Result<f64, MathError> {
    if x < 0.0 {
        Err(MathError::NegativeSquareRoot)
    } else {
        Ok(x.sqrt())
    }
}

fn main() {
    match divide(10.0, 0.0) {
        Ok(result) => println!("结果: {}", result),
        Err(MathError::DivisionByZero) => eprintln!("❌ 除数不能为零"),
        Err(e) => eprintln!("❌ 数学错误: {:?}", e),
    }
}

4.2 实现 Display 和 Error trait

use std::fmt;
use std::error::Error;

#[derive(Debug)]
enum DataError {
    NotFound(String),
    InvalidFormat { field: String, reason: String },
    DatabaseError(String),
}

impl fmt::Display for DataError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            DataError::NotFound(item) => {
                write!(f, "未找到数据: {}", item)
            },
            DataError::InvalidFormat { field, reason } => {
                write!(f, "字段 '{}' 格式无效: {}", field, reason)
            },
            DataError::DatabaseError(msg) => {
                write!(f, "数据库错误: {}", msg)
            },
        }
    }
}

impl Error for DataError {}

fn fetch_user(id: u32) -> Result<String, DataError> {
    if id == 0 {
        return Err(DataError::NotFound(format!("用户ID: {}", id)));
    }
    Ok(format!("User-{}", id))
}

fn main() {
    match fetch_user(0) {
        Ok(user) => println!("✓ {}", user),
        Err(e) => eprintln!("✗ {}", e),
    }
}

4.3 使用 thiserror 库

[dependencies]
thiserror = "1.0"

use thiserror::Error;

#[derive(Error, Debug)]
enum AppError {
    #[error("IO错误: {0}")]
    Io(#[from] std::io::Error),
    
    #[error("解析错误: {0}")]
    Parse(#[from] std::num::ParseIntError),
    
    #[error("用户 '{user}' 未找到")]
    UserNotFound { user: String },
    
    #[error("无效的配置项: {field}")]
    InvalidConfig { field: String },
    
    #[error("数据库错误: {0}")]
    Database(String),
}

fn process_file(path: &str) -> Result<i32, AppError> {
    let content = std::fs::read_to_string(path)?;  // 自动转换 io::Error
    let number: i32 = content.trim().parse()?;      // 自动转换 ParseIntError
    Ok(number * 2)
}

fn main() {
    match process_file("number.txt") {
        Ok(result) => println!("结果: {}", result),
        Err(e) => eprintln!("错误: {}", e),
    }
}

4.4 使用 anyhow 库（应用级错误处理）

[dependencies]
anyhow = "1.0"

use anyhow::{Context, Result, bail};

fn read_config(path: &str) -> Result<String> {
    std::fs::read_to_string(path)
        .context(format!("无法读取配置文件: {}", path))?;
    
    Ok("配置内容".to_string())
}

fn validate_config(content: &str) -> Result<()> {
    if content.is_empty() {
        bail!("配置文件为空");
    }
    Ok(())
}

fn main() -> Result<()> {
    let config = read_config("config.toml")?;
    validate_config(&config)?;
    
    println!("✓ 配置加载成功");
    Ok(())
}

五、错误处理最佳实践

5.1 错误传播策略

use std::error::Error;
use std::fs::File;
use std::io::{self, Read};

// ✓ 策略1：使用 ? 运算符传播错误
fn read_file_propagate(path: &str) -> Result<String, io::Error> {
    let mut file = File::open(path)?;
    let mut content = String::new();
    file.read_to_string(&mut content)?;
    Ok(content)
}

// ✓ 策略2：转换为自定义错误
#[derive(Debug)]
enum FileError {
    IoError(io::Error),
    EmptyFile,
}

impl From<io::Error> for FileError {
    fn from(error: io::Error) -> Self {
        FileError::IoError(error)
    }
}

fn read_file_custom(path: &str) -> Result<String, FileError> {
    let content = std::fs::read_to_string(path)?;
    
    if content.is_empty() {
        return Err(FileError::EmptyFile);
    }
    
    Ok(content)
}

// ✓ 策略3：使用 Box<dyn Error>（灵活但类型擦除）
fn read_file_boxed(path: &str) -> Result<String, Box<dyn Error>> {
    let content = std::fs::read_to_string(path)?;
    Ok(content)
}

5.2 多个错误类型的处理

use std::num::ParseIntError;
use std::io;

fn read_and_parse(path: &str) -> Result<i32, Box<dyn std::error::Error>> {
    let content = std::fs::read_to_string(path)?;  // io::Error
    let number: i32 = content.trim().parse()?;      // ParseIntError
    Ok(number)
}

// 更好的方式：自定义错误枚举
#[derive(Debug)]
enum ProcessError {
    Io(io::Error),
    Parse(ParseIntError),
}

impl From<io::Error> for ProcessError {
    fn from(e: io::Error) -> Self {
        ProcessError::Io(e)
    }
}

impl From<ParseIntError> for ProcessError {
    fn from(e: ParseIntError) -> Self {
        ProcessError::Parse(e)
    }
}

fn read_and_parse_typed(path: &str) -> Result<i32, ProcessError> {
    let content = std::fs::read_to_string(path)?;
    let number: i32 = content.trim().parse()?;
    Ok(number)
}

5.3 早期返回模式

fn validate_user(
    username: &str,
    email: &str,
    age: u32,
) -> Result<(), String> {
    // 早期返回验证失败
    if username.is_empty() {
        return Err("用户名不能为空".to_string());
    }
    
    if !email.contains('@') {
        return Err("邮箱格式无效".to_string());
    }
    
    if age < 18 {
        return Err("年龄必须大于18岁".to_string());
    }
    
    // 所有验证通过
    Ok(())
}

fn main() {
    let users = vec![
        ("", "user@example.com", 25),
        ("alice", "invalid-email", 25),
        ("bob", "bob@example.com", 16),
        ("charlie", "charlie@example.com", 30),
    ];
    
    for (username, email, age) in users {
        match validate_user(username, email, age) {
            Ok(_) => println!("✓ 用户 {} 验证通过", username),
            Err(e) => println!("✗ 验证失败: {}", e),
        }
    }
}

六、实战案例

6.1 案例1：HTTP 客户端错误处理

use std::error::Error;
use std::fmt;

#[derive(Debug)]
enum HttpError {
    NetworkError(String),
    Timeout,
    InvalidResponse { status: u16, body: String },
    ParseError(String),
}

impl fmt::Display for HttpError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            HttpError::NetworkError(msg) => write!(f, "网络错误: {}", msg),
            HttpError::Timeout => write!(f, "请求超时"),
            HttpError::InvalidResponse { status, body } => {
                write!(f, "无效响应 (状态码 {}): {}", status, body)
            },
            HttpError::ParseError(msg) => write!(f, "解析错误: {}", msg),
        }
    }
}

impl Error for HttpError {}

struct HttpClient;

impl HttpClient {
    fn get(&self, url: &str) -> Result<String, HttpError> {
        // 模拟HTTP请求
        if url.contains("timeout") {
            return Err(HttpError::Timeout);
        }
        
        if url.contains("404") {
            return Err(HttpError::InvalidResponse {
                status: 404,
                body: "Not Found".to_string(),
            });
        }
        
        Ok(format!("Response from {}", url))
    }
    
    fn get_with_retry(
        &self,
        url: &str,
        max_retries: u32,
    ) -> Result<String, HttpError> {
        let mut attempts = 0;
        
        loop {
            match self.get(url) {
                Ok(response) => return Ok(response),
                Err(HttpError::Timeout) if attempts < max_retries => {
                    attempts += 1;
                    println!("⏱️  超时，重试 {}/{}", attempts, max_retries);
                    std::thread::sleep(std::time::Duration::from_secs(1));
                },
                Err(e) => return Err(e),
            }
        }
    }
}

fn main() {
    let client = HttpClient;
    
    let urls = vec![
        "https://example.com",
        "https://example.com/timeout",
        "https://example.com/404",
    ];
    
    for url in urls {
        match client.get_with_retry(url, 3) {
            Ok(response) => println!("✓ {}", response),
            Err(e) => eprintln!("✗ {}", e),
        }
    }
}

6.2 案例2：数据验证器

use thiserror::Error;

#[derive(Error, Debug)]
enum ValidationError {
    #[error("字段 '{field}' 不能为空")]
    Empty { field: String },
    
    #[error("字段 '{field}' 长度必须在 {min} 到 {max} 之间")]
    LengthOutOfRange { field: String, min: usize, max: usize },
    
    #[error("字段 '{field}' 格式无效: {reason}")]
    InvalidFormat { field: String, reason: String },
    
    #[error("字段 '{field}' 的值必须大于 {min}")]
    TooSmall { field: String, min: i32 },
}

struct Validator;

impl Validator {
    fn validate_not_empty(field: &str, value: &str) -> Result<(), ValidationError> {
        if value.is_empty() {
            Err(ValidationError::Empty {
                field: field.to_string(),
            })
        } else {
            Ok(())
        }
    }
    
    fn validate_length(
        field: &str,
        value: &str,
        min: usize,
        max: usize,
    ) -> Result<(), ValidationError> {
        let len = value.len();
        if len < min || len > max {
            Err(ValidationError::LengthOutOfRange {
                field: field.to_string(),
                min,
                max,
            })
        } else {
            Ok(())
        }
    }
    
    fn validate_email(field: &str, value: &str) -> Result<(), ValidationError> {
        if !value.contains('@') || !value.contains('.') {
            Err(ValidationError::InvalidFormat {
                field: field.to_string(),
                reason: "必须包含@和.".to_string(),
            })
        } else {
            Ok(())
        }
    }
}

#[derive(Debug)]
struct UserRegistration {
    username: String,
    email: String,
    age: u32,
}

impl UserRegistration {
    fn validate(&self) -> Result<(), Vec<ValidationError>> {
        let mut errors = Vec::new();
        
        if let Err(e) = Validator::validate_not_empty("username", &self.username) {
            errors.push(e);
        }
        
        if let Err(e) = Validator::validate_length("username", &self.username, 3, 20) {
            errors.push(e);
        }
        
        if let Err(e) = Validator::validate_email("email", &self.email) {
            errors.push(e);
        }
        
        if self.age < 18 {
            errors.push(ValidationError::TooSmall {
                field: "age".to_string(),
                min: 18,
            });
        }
        
        if errors.is_empty() {
            Ok(())
        } else {
            Err(errors)
        }
    }
}

fn main() {
    let user = UserRegistration {
        username: "ab".to_string(),
        email: "invalid-email".to_string(),
        age: 16,
    };
    
    match user.validate() {
        Ok(_) => println!("✓ 验证通过"),
        Err(errors) => {
            println!("✗ 验证失败 ({} 个错误):", errors.len());
            for error in errors {
                println!("  - {}", error);
            }
        },
    }
}

七、panic! 与 unwrap

7.1 何时使用 panic!

fn divide(a: i32, b: i32) -> i32 {
    if b == 0 {
        panic!("除数不能为零！");  // ❌ 库代码中避免
    }
    a / b
}

// ✓ 更好的方式
fn divide_safe(a: i32, b: i32) -> Result<i32, String> {
    if b == 0 {
        Err("除数不能为零".to_string())
    } else {
        Ok(a / b)
    }
}

// ✓ 合理使用panic：程序逻辑错误
fn get_config_must_exist() -> String {
    std::env::var("REQUIRED_CONFIG")
        .expect("REQUIRED_CONFIG环境变量必须设置")
}

7.2 自定义 panic 处理

use std::panic;

fn main() {
    // 设置panic钩子
    panic::set_hook(Box::new(|panic_info| {
        if let Some(s) = panic_info.payload().downcast_ref::<&str>() {
            println!("🚨 Panic发生: {}", s);
        } else {
            println!("🚨 Panic发生");
        }
        
        if let Some(location) = panic_info.location() {
            println!("  位置: {}:{}", location.file(), location.line());
        }
    }));
    
    // 捕获panic
    let result = panic::catch_unwind(|| {
        panic!("测试panic");
    });
    
    match result {
        Ok(_) => println!("没有panic"),
        Err(_) => println!("捕获到panic"),
    }
}

八、总结与讨论

Rust的错误处理机制是其类型安全的核心体现：

✅ 显式优于隐式：强制处理错误
✅ 类型安全：编译期保证错误处理
✅ 零成本抽象：Result编译为高效代码
✅ 灵活表达：支持复杂错误场景

核心概念总结：

在这里插入图片描述

讨论问题：

何时使用 unwrap() 是合理的？
thiserror vs anyhow：如何选择？
如何在异步代码中优雅地处理错误？

欢迎分享经验！💬

参考链接

Rust Book - Error Handling：https://doc.rust-lang.org/book/ch09-00-error-handling.html
thiserror文档：https://docs.rs/thiserror
anyhow文档：https://docs.rs/anyhow

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

中间件：高可用、高性能、可扩展三大核心设计原则

AtomGit开源社区

因果一体破局西医：重构底层诊疗逻辑，打通中西医壁垒与现代数理工程本源

AtomGit开源社区

Vllm进行Qwen2-vl部署（包含单卡多卡部署及爬虫请求）

阿里云于今年9月宣布开源第二代视觉语言模型Qwen2-VL，包括 2B、7B、72B三个尺寸及其量化版本模型。Qwen2-VL具备完整图像、多语言的理解能力，性能强劲。相比上代模型，Qwen2-VL 的基础性能全面提升，可以读懂不同分辨率和不同长宽比的图片，在 DocVQA、RealWorldQA、MTVQA 等基准测试创下全球领先的表现；可以理解 20 分钟以上长视频，支持基于视频的问答、对话和