Rust / 系统课时

日志里如何输出完整错误链

日志里如何输出完整错误链

只记录最外层错误常常只得到一句“启动失败”,而真正有用的原因可能藏在两三层 source 之后。本篇用标准库构造并遍历错误链,同时说明为什么应该在统一边界记录一次,而不是每层遇错都重复打印。

学习目标

  • 理解 Rust Error::source 如何形成可遍历的错误链
  • 在日志中同时保留顶层语义与逐层根因
  • 避免同一错误在多层重复记录造成噪声和误判

只打印顶层错误会丢什么

高层错误应该描述业务或操作语义,例如“应用启动失败”;底层错误则说明直接原因,例如“PORT 不是有效整数”。如果只记录顶层 Display,日志会缺少根因;如果每层都各自打印,又会把同一次失败伪装成多次事件。

更稳妥的做法是:底层通过 source 继续向上传递原因,最外层在一个明确的日志边界一次性输出整条链。

构造并遍历完整错误链

下面的完整示例包含三层信息:启动失败、配置字段无效、整数解析失败。log_error_chain 先打印顶层错误,再沿 source() 逐层向下遍历。

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

#[derive(Debug)]
// 配置层保留字段语义与原始解析错误。
struct ConfigError {
    field: &'static str,
    source: ParseIntError,
}

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

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

#[derive(Debug)]
// 启动层只增加高层操作语义,不覆盖原始 source。
struct StartupError {
    source: ConfigError,
}

impl fmt::Display for StartupError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "application startup failed")
    }
}

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

fn load_port() -> Result<u16, StartupError> {
    "not-a-number"
        .parse::<u16>()
        .map_err(|source| ConfigError {
            field: "PORT",
            source,
        })
        .map_err(|source| StartupError { source })
}

fn log_error_chain(err: &(dyn Error)) {
    // 从顶层开始,再按 source 链依次输出每一层原因。
    eprintln!("error: {err}");

    let mut current = err.source();
    let mut level = 1;

    while let Some(source) = current {
        eprintln!("caused by[{level}]: {source}");
        current = source.source();
        level += 1;
    }
}

fn main() {
    if let Err(err) = load_port() {
        // 只在最外层记录一次,内部函数负责传播错误而不是重复打印。
        log_error_chain(&err);
    }
}

预期输出

text
error: application startup failed
caused by[1]: invalid PORT value
caused by[2]: invalid digit found in string

这个输出先给出顶层语义,再按因果顺序展开根因。实际接入 tracing、log 或其他日志库时,也应确认格式化方式是否会自动展开 source;不能假设记录 {err} 就一定包含完整错误链。

把记录动作放在稳定边界

常见边界包括 HTTP 请求入口、消息消费者入口、后台任务执行器和进程主函数。边界以下的函数负责添加上下文并返回错误,边界本身负责决定日志级别、关联请求标识并记录完整链。

如果 load_port、配置加载器和 main 都各自打印同一个错误,一次启动失败会产生多条高度相似日志。监控系统可能把它们误当成多个事件,值班人员也更难判断哪一条才是原始失败。

日志内容要有语义而不是只有根因

完整错误链并不意味着只保留最底层消息。invalid digit found in string 单独看几乎无法判断解析的是端口、订单号还是重试次数;顶层语义同样重要。

因此一条有用的错误日志至少应能回答两件事:正在执行什么操作,以及底层为什么失败。如果系统还有请求 ID、任务 ID 等关联信息,可以在日志字段中补充 <ID>;实际值由运行时生成,避免把动态标识写死在示例或告警规则中。

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

目录与阅读设置

阅读设置

17

记录一个想法

日志里如何输出完整错误链

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

登录哪都通