Rust / 系统课时

正确实现 Display 与 Error

正确实现 Display 与 Error

自定义错误不仅要“能打印”,还要同时服务两类读者:Display 给最终用户或日志提供可读上下文,Error::source 则保留底层原因,供错误链和诊断工具继续向下追踪。本节用一个完整示例把两者职责分开。

学习目标

  • 正确区分 Display、Debug 与 Error::source 的职责
  • 为包装型错误实现稳定、可追踪的错误链
  • 避免把底层错误文本硬拼进上层消息造成信息重复

Display 与 Error 各负责什么

std::error::Error 要求错误类型同时实现 Debug 和 Display。其中 Display 应描述“这一层发生了什么”,例如“无法读取配置文件”;如果当前错误包装了另一个错误,则通过 source() 返回底层错误,而不是把整条原因链都塞进同一段文字。

这种分工让调用方可以自由选择展示深度:面向用户时只打印最外层 Display,诊断时再沿 source() 逐层查看原因。错误类型因此既保持可读,也不会丢失结构化因果关系。

完整实现一个错误链

下面定义一个上层 LoadConfigError,内部保存 io::Error。Display 只补充配置文件这一层的上下文,source() 返回真正的底层原因。为了让输出不受操作系统错误文本影响,示例直接构造一个确定的 io::Error。

rust
use std::{error::Error, fmt, io};

#[derive(Debug)]
struct LoadConfigError {
    path: String,
    source: io::Error,
}

impl fmt::Display for LoadConfigError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "无法读取配置文件 {}", self.path)
    }
}

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

fn load_config(path: &str) -> Result<String, LoadConfigError> {
    let source = io::Error::new(io::ErrorKind::NotFound, "file not found");
    Err(LoadConfigError {
        path: path.to_owned(),
        source,
    })
}

fn main() {
    if let Err(err) = load_config("<PATH>") {
        println!("display: {err}");

        if let Some(source) = err.source() {
            println!("source: {source}");
        }
    }
}

预期输出

text
display: 无法读取配置文件 <PATH>
source: file not found

这里的 <PATH> 是路径占位符,实际值通常来自配置项或函数参数。#[derive(Debug)] 也不是可有可无:标准 Error trait 本身要求实现 Debug。

为什么不要在 Display 里重复 source

如果把底层原因也拼进 Display,例如输出“无法读取配置文件:file not found”,错误链打印器随后再遍历 source() 时,就可能重复显示同一原因。更稳妥的做法是让每一层只描述自己的语义,再用错误链保存因果关系。

哪些错误应该返回 source

只有当前错误确实包装了另一个实现 Error 的原因时,才应返回 Some(...)。纯业务状态错误,例如“余额不足”或“订单已取消”,如果不存在更底层的失败原因,让 source() 保持默认的 None 即可。

还要避免在 source() 中临时创建错误对象。返回值是对当前错误内部对象的借用,因此底层错误必须作为字段被真实保存。工程上坚持“上层补充语义,底层保留原因”,自定义错误就能同时满足可读性与可诊断性。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

正确实现 Display 与 Error

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通