Rust / 系统课时
补齐上下文日志与退出码
补齐上下文日志与退出码
应用内部返回 Result 只是第一步;真正到进程入口时,还要把“哪里失败、处理哪个对象、为什么失败”写进日志,并把失败类型转换成稳定退出码。这样人工排障、Shell 脚本和容器编排都能得到明确结果。
学习目标
- 在应用入口为底层错误补充场景、路径和阶段信息。
- 统一把诊断信息写到标准错误输出,避免业务输出与错误日志混在一起。
- 为不同失败类型定义稳定退出码,并验证调用方能够识别。
把错误信息留到应用边界统一处理
库函数适合返回结构化错误,不应该在每一层都 eprintln!。否则同一个错误可能被重复打印,而且底层代码不知道当前业务场景。更合适的做法是:业务函数保留错误类型,应用入口补充场景字段并决定如何展示。
下面的完整程序读取一个只包含端口号的配置文件,并把三类失败映射为不同退出码:参数错误为 2,文件读取失败为 3,配置内容非法为 4。
use std::env;
use std::fmt;
use std::fs;
use std::num::ParseIntError;
use std::process::ExitCode;
#[derive(Debug)]
enum AppError {
Usage,
ReadConfig {
path: String,
source: std::io::Error,
},
InvalidPort {
path: String,
raw: String,
source: ParseIntError,
},
}
impl fmt::Display for AppError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
AppError::Usage => write!(f, "usage: app <config-path>"),
AppError::ReadConfig { path, source } => {
write!(f, "cannot read config path={path}: {source}")
}
AppError::InvalidPort { path, raw, source } => {
write!(f, "invalid port path={path} value={raw:?}: {source}")
}
}
}
}
fn load_port(path: &str) -> Result<u16, AppError> {
let text = fs::read_to_string(path).map_err(|source| AppError::ReadConfig {
path: path.to_owned(),
source,
})?;
let raw = text.trim().to_owned();
raw.parse::<u16>().map_err(|source| AppError::InvalidPort {
path: path.to_owned(),
raw,
source,
})
}
fn run() -> Result<u16, AppError> {
let path = env::args().nth(1).ok_or(AppError::Usage)?;
load_port(&path)
}
fn main() -> ExitCode {
match run() {
Ok(port) => {
println!("port={port}");
ExitCode::SUCCESS
}
Err(err) => {
let (stage, code) = match &err {
AppError::Usage => ("startup", 2),
AppError::ReadConfig { .. } => ("load_config", 3),
AppError::InvalidPort { .. } => ("parse_config", 4),
};
eprintln!("level=error stage={stage} message={err}");
ExitCode::from(code)
}
}
}预期结果
保存为 src/main.rs 后,cargo check 能通过编译;成功时标准输出只包含 port=<PORT>,失败时错误信息只写入标准错误输出。这里的关键不是日志格式本身,而是只在边界打印一次。load_port 负责保留结构化错误,main 才知道当前错误属于启动、读取配置还是解析配置,因此由入口统一添加 stage 并决定退出状态。
用稳定退出码表达失败类别
退出码是程序对外的机器接口。日志给人看,退出码给调用方判断。不要把不同错误都压成 1,也不要把底层操作系统错误码直接透传,因为那会让上层脚本依赖平台细节。
可以用一个缺失文件验证读取失败路径:
cargo run -- <PATH>
echo $?预期输出
level=error stage=load_config message=cannot read config path=<PATH>: <OS_ERROR>
3<PATH> 和 <OS_ERROR> 会随实际路径与操作系统变化。脚本不需要解析整行日志,只需判断退出码 3 即可知道“配置文件无法读取”。
给日志补上下文而不是重复错误
“读取失败”本身信息不足。诊断日志至少应回答三个问题:失败发生在哪个阶段、处理的是哪个对象、底层原因是什么。本例的 stage、path 和 source 分别对应这三类信息。
如果以后引入 tracing、log 或结构化日志平台,也应保留同样的边界原则:业务层返回错误,入口或请求边界统一记录场景字段。这样既能避免重复日志,也能让错误链保留足够的信息。
验证成功与失败都符合契约
准备一个内容为合法端口号的文件后运行程序,成功路径应返回 0,并且不产生错误日志。再分别测试文件不存在和内容不是数字的情况,确认退出码为 3 与 4。
printf '8080' > <PATH>
cargo run -- <PATH>
echo $?预期输出
port=8080
0应用边界最终要形成清晰契约:内部错误保持结构化,面向人的诊断信息进入标准错误输出,面向自动化调用方的失败类型进入稳定退出码。三者职责分开后,排障信息更完整,调用方式也更可靠。