Rust / 系统课时

CLI 如何映射退出码与错误

CLI 如何映射退出码与错误

命令行程序既要让人看懂错误,也要让脚本可靠判断失败原因。本节用 Rust 把内部错误集中映射为退出码,并把诊断信息写到标准错误,形成稳定、可测试的 CLI 边界。

学习目标

  • 区分标准输出、标准错误与进程退出码的职责
  • 为常见失败设计稳定且可脚本化的退出码
  • 用 std::process::ExitCode 集中完成错误到退出码的映射

退出码和错误文本各管什么

CLI 对外其实有两条错误通道:退出码给程序判断,错误文本给人阅读。成功通常返回 0;失败返回非零值。调用方不应该解析一句自然语言来判断“文件不存在”还是“参数错误”,否则只要文案调整,脚本就可能失效。

标准输出 stdout 应保留给正常结果,标准错误 stderr 用于诊断信息。这样即使用户把正常输出重定向到文件,错误仍然可以显示在终端,脚本也能分别处理两类数据。

先设计稳定的退出码

退出码没有一套适用于所有应用的业务标准,因此更重要的是在自己的工具中保持稳定并写入文档。可以先定义少量类别,例如:

退出码 含义 适合脚本采取的动作
0 成功 继续后续步骤
2 用法或参数错误 修正调用参数
3 目标资源不存在 检查路径、名称或前置步骤
4 输入内容不合法 修正输入数据
1 其他未分类失败 记录诊断并停止

在 Unix shell 中,126、127 以及某些 128 + signal 值常被 shell 本身用于表示“不可执行”“命令不存在”或信号终止。自定义业务退出码时通常选择较小、明确的值,更不容易与这些约定混淆。

在边界统一完成映射

下面的完整程序把业务错误先表示成 CliError,直到 main 边界才决定退出码和展示文案。这样核心逻辑不需要知道 stderr 或进程退出语义。

rust
use std::env;
use std::process::ExitCode;

#[derive(Debug)]
enum CliError {
    Usage,
    NotFound,
    InvalidInput,
}

fn run(args: &[String]) -> Result<String, CliError> {
    let Some(value) = args.get(1) else {
        return Err(CliError::Usage);
    };

    match value.as_str() {
        "missing" => Err(CliError::NotFound),
        "bad" => Err(CliError::InvalidInput),
        other => Ok(format!("accepted: {other}")),
    }
}

fn report(error: CliError) -> ExitCode {
    // 映射只发生在 CLI 边界,内部错误类型不承担进程协议职责。
    let (code, message) = match error {
        CliError::Usage => (2, "usage: cli-demo <value>"),
        CliError::NotFound => (3, "error: requested resource was not found"),
        CliError::InvalidInput => (4, "error: input value is invalid"),
    };

    eprintln!("{message}");
    ExitCode::from(code)
}

fn main() -> ExitCode {
    let args: Vec<String> = env::args().collect();

    match run(&args) {
        Ok(output) => {
            println!("{output}");
            ExitCode::SUCCESS
        }
        Err(error) => report(error),
    }
}

预期结果

text
源码可由 rustc 编译;成功路径写 stdout,失败路径写 stderr,并返回对应的非零退出码。

保存为 main.rs 后,可以直接验证不同分支:

bash
rustc main.rs -o cli-demo
./cli-demo ok
echo $?
./cli-demo missing
echo $?
./cli-demo bad
echo $?

预期输出

text
accepted: ok
0
error: requested resource was not found
3
error: input value is invalid
4

不同 shell 对 stderr 与 stdout 的显示顺序可能略有差异,但每次执行后的退出码应分别为 0、3、4。

让脚本只依赖稳定接口

调用方应优先判断退出码,而不是匹配错误文本。例如下面脚本只关心“资源不存在”这一类失败:

bash
./cli-demo missing
code=$?

if [ "$code" -eq 3 ]; then
  echo "resource missing; create it before retrying"
fi

预期输出

text
error: requested resource was not found
resource missing; create it before retrying

错误文案可以随着可读性要求改进,但退出码一旦被外部脚本使用,就应像命令参数一样谨慎变更。如果确实要调整含义,最好在版本说明中明确兼容性影响。

测试时同时验证文本和退出码

CLI 测试至少要覆盖成功、参数错误和关键业务失败。测试重点不是把每个内部错误枚举都暴露出去,而是确认外部可观察行为稳定:成功走 stdout 且返回 0,失败走 stderr 且返回预定非零值。

对于机器需要消费的复杂错误信息,可以增加 --json 等显式机器输出模式;普通交互模式仍应保持短、可读,并避免打印实现细节、堆栈或敏感数据。

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

目录与阅读设置

阅读设置

17

记录一个想法

CLI 如何映射退出码与错误

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

登录哪都通