Rust错误处理增强库culpa的使用指南

culpa是一个Rust错误处理增强库，提供了灵活的错误链和上下文捕获功能，能够显著优化Rust程序的错误管理体验。

主要特性

1. 简洁的错误链构建
2. 丰富的上下文捕获能力
3. 与标准库std::error::Error无缝集成
4. 零成本抽象

基本使用方法

首先在Cargo.toml中添加依赖：

[dependencies]
culpa = "0.3"

定义自定义错误

use culpa::{throw, throws};

#[derive(Debug, thiserror::Error)]
enum MyError {
    #[error("IO error occurred")]
    Io(#[from] std::io::Error),
    #[error("Parse error occurred")]
    Parse(#[from] std::num::ParseIntError),
}

使用throws宏简化错误处理

#[throws(MyError)]
fn read_and_parse_file(path: &str) -> i32 {
    let content = std::fs::read_to_string(path)?;
    content.trim().parse()?
}

// 等价于手动编写的版本：
fn read_and_parse_file_manual(path: &str) -> Result<i32, MyError> {
    let content = std::fs::read_to_string(path).map_err(MyError::Io)?;
    content.trim().parse().map_err(MyError::Parse)
}

错误链和上下文

use culpa::Context;

fn process_data() -> Result<(), MyError> {
    let value = read_and_parse_file("data.txt")
        .context("Failed to process data file")?;
    
    // 更多处理...
    Ok(())
}

高级用法：错误包装和转换

#[throws]
fn complex_operation() -> i32 {
    let x: i32 = another_operation().context("In complex_operation")?;
    x * 2
}

fn another_operation() -> Result<i32, std::num::ParseIntError> {
    "123".parse()
}

使用throw!宏提前返回错误

#[throws(MyError)]
fn validate_input(input: &str) -> i32 {
    if input.is_empty() {
        throw!("Input cannot be empty");
    }
    
    input.parse()?
}

最佳实践

1. 为应用程序定义统一的错误类型枚举
2. 使用#[throws]宏减少样板代码
3. 在关键路径添加有意义的上下文
4. 组合使用thiserror和culpa获得最佳体验

示例：完整错误处理流程

use culpa::{throws, throw, Context};
use thiserror::Error;

#[derive(Debug, Error)]
enum AppError {
    #[error("Configuration error: {0}")]
    Config(String),
    #[error("Network error")]
    Network(#[from] reqwest::Error),
    #[error("Database error")]
    Db(#[from] sqlx::Error),
}

#[throws(AppError)]
async fn fetch_user_data(user_id: &str) -> UserData {
    if user_id.is_empty() {
        throw!(AppError::Config("Empty user ID".to_string()));
    }
    
    let db_user = query_database(user_id)
        .await
        .context("Failed to query user from database")?;
    
    let external_data = fetch_from_external_service(&db_user.api_key)
        .await
        .context("Failed to fetch external data")?;
    
    combine_data(db_user, external_data)
}

完整示例demo

下面是一个完整的示例，展示了如何使用culpa进行错误处理：

use culpa::{throws, throw, Context};
use thiserror::Error;
use std::fs::File;
use std::io::Read;

// 1. 定义自定义错误类型
#[derive(Debug, Error)]
enum AppError {
    #[error("Configuration error: {0}")]
    Config(String),
    #[error("IO error")]
    Io(#[from] std::io::Error),
    #[error("Parse error")]
    Parse(#[from] std::num::ParseIntError),
    #[error("Validation error: {0}")]
    Validation(String),
}

// 2. 使用throws宏简化函数签名
#[throws(AppError)]
fn read_config_file(path: &str) -> i32 {
    // 3. 使用throw!宏提前返回错误
    if path.is_empty() {
        throw!(AppError::Config("Empty path".to_string()));
    }
    
    let mut file = File::open(path)?;
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;
    
    // 4. 添加上下文信息
    let value = contents.trim().parse::<i32>()
        .context("Failed to parse config value")?;
    
    // 5. 自定义验证
    if value < 0 {
        throw!(AppError::Validation("Value must be positive".to_string()));
    }
    
    value
}

// 6. 主函数处理错误
fn main() {
    match read_config_file("config.txt") {
        Ok(value) => println!("Config value: {}", value),
        Err(e) => {
            // 7. 打印完整的错误链
            eprintln!("Error: {}", e);
            if let Some(source) = e.source() {
                eprintln!("Caused by: {}", source);
            }
        }
    }
}

// 8. 测试函数
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_read_config() {
        // 测试空路径
        assert!(matches!(
            read_config_file(""),
            Err(AppError::Config(_))
        ));
        
        // 测试无效数字
        let tmp_file = tempfile::NamedTempFile::new().unwrap();
        std::fs::write(tmp_file.path(), "invalid").unwrap();
        assert!(matches!(
            read_config_file(tmp_file.path().to_str().unwrap()),
            Err(AppError::Parse(_))
        ));
        
        // 测试负值
        let tmp_file = tempfile::NamedTempFile::new().unwrap();
        std::fs::write(tmp_file.path(), "-10").unwrap();
        assert!(matches!(
            read_config_file(tmp_file.path().to_str().unwrap()),
            Err(AppError::Validation(_))
        ));
    }
}

这个完整示例展示了：

1. 自定义错误类型的定义
2. 使用throws宏简化函数签名
3. 使用throw!宏提前返回错误
4. 添加上下文信息
5. 错误链的处理
6. 主函数中的错误处理
7. 测试用例

culpa通过简化错误处理流程和提供丰富的上下文信息，使得Rust程序的错误处理更加清晰和可维护。