Rust / 系统课时
日志里如何输出完整错误链
日志里如何输出完整错误链
只记录最外层错误常常只得到一句“启动失败”,而真正有用的原因可能藏在两三层 source 之后。本篇用标准库构造并遍历错误链,同时说明为什么应该在统一边界记录一次,而不是每层遇错都重复打印。
学习目标
- 理解 Rust
Error::source如何形成可遍历的错误链 - 在日志中同时保留顶层语义与逐层根因
- 避免同一错误在多层重复记录造成噪声和误判
只打印顶层错误会丢什么
高层错误应该描述业务或操作语义,例如“应用启动失败”;底层错误则说明直接原因,例如“PORT 不是有效整数”。如果只记录顶层 Display,日志会缺少根因;如果每层都各自打印,又会把同一次失败伪装成多次事件。
更稳妥的做法是:底层通过 source 继续向上传递原因,最外层在一个明确的日志边界一次性输出整条链。
构造并遍历完整错误链
下面的完整示例包含三层信息:启动失败、配置字段无效、整数解析失败。log_error_chain 先打印顶层错误,再沿 source() 逐层向下遍历。
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);
}
}预期输出
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>;实际值由运行时生成,避免把动态标识写死在示例或告警规则中。