Rust / 系统课时

补齐上下文日志与退出码

补齐上下文日志与退出码

应用内部返回 Result 只是第一步;真正到进程入口时,还要把“哪里失败、处理哪个对象、为什么失败”写进日志,并把失败类型转换成稳定退出码。这样人工排障、Shell 脚本和容器编排都能得到明确结果。

学习目标

  • 在应用入口为底层错误补充场景、路径和阶段信息。
  • 统一把诊断信息写到标准错误输出,避免业务输出与错误日志混在一起。
  • 为不同失败类型定义稳定退出码,并验证调用方能够识别。

把错误信息留到应用边界统一处理

库函数适合返回结构化错误,不应该在每一层都 eprintln!。否则同一个错误可能被重复打印,而且底层代码不知道当前业务场景。更合适的做法是:业务函数保留错误类型,应用入口补充场景字段并决定如何展示。

下面的完整程序读取一个只包含端口号的配置文件,并把三类失败映射为不同退出码:参数错误为 2,文件读取失败为 3,配置内容非法为 4。

rust
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)
        }
    }
}

预期结果

text
保存为 src/main.rs 后,cargo check 能通过编译;成功时标准输出只包含 port=<PORT>,失败时错误信息只写入标准错误输出。

这里的关键不是日志格式本身,而是只在边界打印一次。load_port 负责保留结构化错误,main 才知道当前错误属于启动、读取配置还是解析配置,因此由入口统一添加 stage 并决定退出状态。

用稳定退出码表达失败类别

退出码是程序对外的机器接口。日志给人看,退出码给调用方判断。不要把不同错误都压成 1,也不要把底层操作系统错误码直接透传,因为那会让上层脚本依赖平台细节。

可以用一个缺失文件验证读取失败路径:

bash
cargo run -- <PATH>
echo $?

预期输出

text
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。

bash
printf '8080' > <PATH>
cargo run -- <PATH>
echo $?

预期输出

text
port=8080
0

应用边界最终要形成清晰契约:内部错误保持结构化,面向人的诊断信息进入标准错误输出,面向自动化调用方的失败类型进入稳定退出码。三者职责分开后,排障信息更完整,调用方式也更可靠。

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

目录与阅读设置

阅读设置

17

记录一个想法

补齐上下文日志与退出码

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

登录哪都通