Error 的 source 方法 ​

核心概念 ​

source() 是 std::error::Error trait 中的核心方法,用于返回导致当前错误的底层原因(即"源错误")。通过 source() 方法,多层错误之间形成一条链式结构——每个错误指向导致它的上一个错误,一直追溯到最底层的根本原因。这种错误链机制让你在排查问题时不仅能看到表面的错误描述,还能逐层追踪到真正出问题的地方。

rust
use std::error::Error;
use std::fmt;
use std::io;

// 底层错误:数据库错误
#[derive(Debug)]
struct DbError {
    message: String,
    source: io::Error,  // 底层 IO 错误
}

impl fmt::Display for DbError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "数据库错误: {}", self.message)
    }
}

impl Error for DbError {
    // source() 返回导致此错误的底层原因
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.source)
    }
}

// 上层错误:应用错误
#[derive(Debug)]
struct AppError {
    message: String,
    source: Option<Box<dyn Error>>,
}

impl fmt::Display for AppError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "应用错误: {}", self.message)
    }
}

impl Error for AppError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        self.source.as_deref()
    }
}

fn main() {
    // 构造一条三层错误链:AppError → DbError → io::Error
    let io_err = io::Error::new(io::ErrorKind::ConnectionRefused, "连接被拒绝");
    let db_err = DbError {
        message: String::from("查询用户表失败"),
        source: io_err,
    };
    let app_err = AppError {
        message: String::from("加载用户数据失败"),
        source: Some(Box::new(db_err)),
    };

    // 遍历错误链
    println!("错误: {}", app_err);
    let mut current: Option<&dyn Error> = app_err.source();
    let mut depth = 1;
    while let Some(cause) = current {
        println!("  原因{}: {}", depth, cause);
        current = cause.source();
        depth += 1;
    }
}

source() 方法签名 ​

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

// source() 的签名:
// fn source(&self) -> Option<&(dyn Error + 'static)>
//
// 返回 Option:可能有底层错误,也可能没有(根错误)
// &(dyn Error + 'static):底层错误的引用,要求 'static 生命周期

// 没有底层原因的错误(根错误)
#[derive(Debug)]
struct SimpleError(String);

impl fmt::Display for SimpleError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl Error for SimpleError {
    // 默认实现就是返回 None,可以不写
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        None
    }
}

// 有底层原因的错误
#[derive(Debug)]
struct WrappedError {
    message: String,
    cause: SimpleError,  // 直接持有底层错误
}

impl fmt::Display for WrappedError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.message)
    }
}

impl Error for WrappedError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.cause)  // 返回底层错误的引用
    }
}

fn main() {
    let root = SimpleError(String::from("磁盘空间不足"));
    println!("根错误 source: {:?}", root.source());  // None

    let wrapped = WrappedError {
        message: String::from("保存文件失败"),
        cause: SimpleError(String::from("磁盘空间不足")),
    };
    println!("包装错误 source: {}", wrapped.source().unwrap());
}

构建错误链 ​

枚举错误类型的 source 实现 ​

rust
use std::error::Error;
use std::fmt;
use std::io;
use std::num::ParseIntError;

#[derive(Debug)]
enum DataError {
    // 包装 io::Error
    FileAccess(io::Error),
    // 包装 ParseIntError
    NumberParse { value: String, source: ParseIntError },
    // 自有错误(没有底层原因)
    Validation(String),
    // 包装另一个自定义错误
    Processing { step: String, source: Box<dyn Error> },
}

impl fmt::Display for DataError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            DataError::FileAccess(e) => write!(f, "文件访问失败: {}", e),
            DataError::NumberParse { value, .. } => {
                write!(f, "解析 '{}' 为数字失败", value)
            }
            DataError::Validation(msg) => write!(f, "验证失败: {}", msg),
            DataError::Processing { step, .. } => {
                write!(f, "处理步骤 '{}' 失败", step)
            }
        }
    }
}

impl Error for DataError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            DataError::FileAccess(e) => Some(e),
            DataError::NumberParse { source, .. } => Some(source),
            DataError::Validation(_) => None,  // 没有底层原因
            DataError::Processing { source, .. } => Some(source.as_ref()),
        }
    }
}

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

fn read_and_parse(path: &str) -> Result<Vec<i32>, DataError> {
    let content = std::fs::read_to_string(path)?;

    let mut numbers = Vec::new();
    for line in content.lines() {
        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue;
        }
        let n = trimmed.parse::<i32>().map_err(|e| DataError::NumberParse {
            value: trimmed.to_string(),
            source: e,
        })?;
        numbers.push(n);
    }

    if numbers.is_empty() {
        return Err(DataError::Validation(String::from("文件中没有数字")));
    }

    Ok(numbers)
}

fn main() {
    match read_and_parse("numbers.txt") {
        Ok(nums) => println!("数字: {:?}", nums),
        Err(e) => {
            println!("错误: {}", e);
            if let Some(source) = e.source() {
                println!("  底层原因: {}", source);
            }
        }
    }
}

遍历完整错误链的工具函数 ​

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

// 通用的错误链遍历函数
fn error_chain(err: &dyn Error) -> Vec<String> {
    let mut chain = vec![err.to_string()];
    let mut current = err.source();
    while let Some(cause) = current {
        chain.push(cause.to_string());
        current = cause.source();
    }
    chain
}

// 格式化错误链为多行字符串
fn format_error_chain(err: &dyn Error) -> String {
    let chain = error_chain(err);
    let mut result = String::new();
    for (i, msg) in chain.iter().enumerate() {
        if i == 0 {
            result.push_str(&format!("错误: {}\n", msg));
        } else {
            result.push_str(&format!("{}↳ 原因: {}\n", "  ".repeat(i), msg));
        }
    }
    result
}

// 获取根本原因(错误链的最后一个)
fn root_cause(err: &dyn Error) -> &dyn Error {
    let mut current = err;
    while let Some(source) = current.source() {
        current = source;
    }
    current
}

// 示例错误类型
#[derive(Debug)]
struct Level1Error(String);
#[derive(Debug)]
struct Level2Error { msg: String, source: Level1Error }
#[derive(Debug)]
struct Level3Error { msg: String, source: Level2Error }

impl fmt::Display for Level1Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "L1: {}", self.0)
    }
}
impl fmt::Display for Level2Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "L2: {}", self.msg)
    }
}
impl fmt::Display for Level3Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "L3: {}", self.msg)
    }
}

impl Error for Level1Error {}
impl Error for Level2Error {
    fn source(&self) -> Option<&(dyn Error + 'static)> { Some(&self.source) }
}
impl Error for Level3Error {
    fn source(&self) -> Option<&(dyn Error + 'static)> { Some(&self.source) }
}

fn main() {
    let err = Level3Error {
        msg: String::from("请求处理失败"),
        source: Level2Error {
            msg: String::from("数据库查询失败"),
            source: Level1Error(String::from("TCP 连接超时")),
        },
    };

    // 格式化输出
    print!("{}", format_error_chain(&err));

    // 获取根本原因
    println!("\n根本原因: {}", root_cause(&err));

    // 获取链的长度
    let chain = error_chain(&err);
    println!("错误链深度: {}", chain.len());
}

source 在日志和调试中的应用 ​

rust
use std::error::Error;
use std::fmt;
use std::io;

#[derive(Debug)]
enum ServerError {
    Bind { addr: String, source: io::Error },
    Handler { path: String, source: Box<dyn Error> },
    Timeout { duration_ms: u64 },
}

impl fmt::Display for ServerError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ServerError::Bind { addr, .. } => write!(f, "绑定 {} 失败", addr),
            ServerError::Handler { path, .. } => write!(f, "处理 {} 时出错", path),
            ServerError::Timeout { duration_ms } => {
                write!(f, "请求超时 ({}ms)", duration_ms)
            }
        }
    }
}

impl Error for ServerError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            ServerError::Bind { source, .. } => Some(source),
            ServerError::Handler { source, .. } => Some(source.as_ref()),
            ServerError::Timeout { .. } => None,
        }
    }
}

// 日志记录函数:自动展开错误链
fn log_error(context: &str, err: &dyn Error) {
    eprintln!("[ERROR] {}: {}", context, err);

    let mut depth = 0;
    let mut current = err.source();
    while let Some(cause) = current {
        depth += 1;
        eprintln!("[ERROR]   {}caused by: {}", "  ".repeat(depth - 1), cause);
        current = cause.source();
    }
}

fn simulate_server() -> Result<(), ServerError> {
    // 模拟绑定失败
    let io_err = io::Error::new(
        io::ErrorKind::AddrInUse,
        "地址已被占用",
    );
    Err(ServerError::Bind {
        addr: String::from("0.0.0.0:8080"),
        source: io_err,
    })
}

fn main() {
    match simulate_server() {
        Ok(()) => println!("服务器启动成功"),
        Err(e) => {
            log_error("服务器启动", &e);

            // 根据 source 的具体类型做特定处理
            if let ServerError::Bind { source, addr } = &e {
                match source.kind() {
                    io::ErrorKind::AddrInUse => {
                        eprintln!("建议: 端口 {} 已被占用,请更换端口", addr);
                    }
                    io::ErrorKind::PermissionDenied => {
                        eprintln!("建议: 需要管理员权限绑定 {}", addr);
                    }
                    _ => {
                        eprintln!("建议: 检查网络配置");
                    }
                }
            }
        }
    }
}

基本示例 ​

用 source 方法实现一个完整的订单处理错误追踪系统:

rust
use std::error::Error;
use std::fmt;
use std::collections::HashMap;

// 第一层:库存错误
#[derive(Debug)]
enum InventoryError {
    OutOfStock { item: String, available: u32, requested: u32 },
    ItemNotFound(String),
}

impl fmt::Display for InventoryError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            InventoryError::OutOfStock { item, available, requested } => {
                write!(f, "'{}' 库存不足(库存{},需要{})", item, available, requested)
            }
            InventoryError::ItemNotFound(item) => write!(f, "商品 '{}' 不存在", item),
        }
    }
}

impl Error for InventoryError {}

// 第二层:支付错误
#[derive(Debug)]
enum PaymentError {
    InsufficientFunds { balance: f64, amount: f64 },
    InvalidCard(String),
}

impl fmt::Display for PaymentError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PaymentError::InsufficientFunds { balance, amount } => {
                write!(f, "余额不足(余额{:.2},需要{:.2})", balance, amount)
            }
            PaymentError::InvalidCard(msg) => write!(f, "银行卡无效: {}", msg),
        }
    }
}

impl Error for PaymentError {}

// 第三层:订单错误(包装前两层)
#[derive(Debug)]
enum OrderError {
    Inventory { order_id: u64, source: InventoryError },
    Payment { order_id: u64, source: PaymentError },
    Validation(String),
}

impl fmt::Display for OrderError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            OrderError::Inventory { order_id, .. } => {
                write!(f, "订单#{} 库存检查失败", order_id)
            }
            OrderError::Payment { order_id, .. } => {
                write!(f, "订单#{} 支付失败", order_id)
            }
            OrderError::Validation(msg) => write!(f, "订单验证失败: {}", msg),
        }
    }
}

impl Error for OrderError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            OrderError::Inventory { source, .. } => Some(source),
            OrderError::Payment { source, .. } => Some(source),
            OrderError::Validation(_) => None,
        }
    }
}

// 库存系统
struct Inventory {
    stock: HashMap<String, u32>,
}

impl Inventory {
    fn new() -> Self {
        let mut stock = HashMap::new();
        stock.insert(String::from("键盘"), 5);
        stock.insert(String::from("鼠标"), 0);
        stock.insert(String::from("显示器"), 3);
        Inventory { stock }
    }

    fn check(&self, item: &str, qty: u32) -> Result<(), InventoryError> {
        let available = self.stock.get(item)
            .ok_or_else(|| InventoryError::ItemNotFound(item.to_string()))?;

        if *available < qty {
            return Err(InventoryError::OutOfStock {
                item: item.to_string(),
                available: *available,
                requested: qty,
            });
        }
        Ok(())
    }
}

// 支付系统
fn process_payment(amount: f64, balance: f64) -> Result<(), PaymentError> {
    if balance < amount {
        return Err(PaymentError::InsufficientFunds { balance, amount });
    }
    Ok(())
}

// 订单处理
fn place_order(
    order_id: u64,
    item: &str,
    qty: u32,
    price: f64,
    balance: f64,
) -> Result<String, OrderError> {
    if qty == 0 {
        return Err(OrderError::Validation(String::from("数量不能为 0")));
    }

    let inventory = Inventory::new();

    // 检查库存
    inventory.check(item, qty).map_err(|e| OrderError::Inventory {
        order_id,
        source: e,
    })?;

    // 处理支付
    let total = price * qty as f64;
    process_payment(total, balance).map_err(|e| OrderError::Payment {
        order_id,
        source: e,
    })?;

    Ok(format!("订单#{} 成功: {} x{} = ¥{:.2}", order_id, item, qty, total))
}

// 完整的错误报告
fn report_error(err: &dyn Error) {
    eprintln!("--- 错误报告 ---");
    eprintln!("描述: {}", err);

    let mut level = 0;
    let mut current = err.source();
    while let Some(cause) = current {
        level += 1;
        eprintln!("第{}层原因: {}", level, cause);
        current = cause.source();
    }
    eprintln!("----------------");
}

fn main() {
    let orders = vec![
        (1001, "键盘", 2, 299.0, 1000.0),    // 成功
        (1002, "鼠标", 1, 99.0, 500.0),       // 库存不足
        (1003, "耳机", 1, 199.0, 500.0),      // 商品不存在
        (1004, "显示器", 1, 2999.0, 1000.0),  // 余额不足
        (1005, "键盘", 0, 299.0, 500.0),      // 数量为 0
    ];

    for (id, item, qty, price, balance) in orders {
        match place_order(id, item, qty, price, balance) {
            Ok(msg) => println!("{}", msg),
            Err(e) => report_error(&e),
        }
        println!();
    }
}

常见问题 ​

问题一:source() 为什么返回 Option?

因为不是所有错误都有底层原因。根错误(最底层的错误)没有 source,返回 None。中间层错误包装了底层错误,返回 Some。这样通过 while let 就能自然终止遍历。

问题二:source() 的 'static 约束是什么意思?

&(dyn Error + 'static) 中的 'static 表示底层错误类型不能包含非静态引用。这是为了让错误链可以安全地在线程间传递。大多数错误类型自然满足这个约束。

问题三:错误链应该有多深?

实际项目中通常 2-4 层。每层代表一个抽象层级(如 IO → 数据库 → 服务 → API)。过深的错误链说明架构可能需要简化。

问题四:source() 和 Display 的消息应该重复吗?

不应该。Display 描述当前层的错误,source() 返回底层原因。日志系统遍历错误链时会自动组合各层消息,所以每层只描述自己这层的信息就够了。

适用场景 ​

  • 分层架构:每层包装下层错误并提供自己的上下文
  • 调试排查:沿错误链追踪到根本原因
  • 日志系统:自动记录完整的错误上下文
  • 错误报告:生成包含完整因果链的错误报告

注意事项 ​

  • source() 默认返回 None,有底层错误时需要手动实现
  • 每层错误的 Display 只描述当前层的信息
  • 底层错误类型必须满足 'static 约束
  • 用 Box<dyn Error> 可以持有任意类型的底层错误
  • 遍历错误链时用 while let Some(cause) = current.source()
  • 根错误的 source() 返回 None,遍历自然终止

总结 ​

source() 方法是 Error trait 中构建错误链的关键。每个错误通过 source() 返回导致它的底层错误引用,形成从表层到根因的链式结构。遍历错误链只需要一个简单的 while let 循环。在分层架构中,每层定义自己的错误类型并包装下层错误,source() 指向直接原因,Display 只描述当前层信息。这种机制让错误追踪变得清晰——从"请求处理失败"到"数据库查询失败"再到"TCP 连接超时",层层剥开找到根本原因。根错误返回 None,自然终止链的遍历。