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 或进程退出语义。
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),
}
}预期结果
源码可由 rustc 编译;成功路径写 stdout,失败路径写 stderr,并返回对应的非零退出码。保存为 main.rs 后,可以直接验证不同分支:
rustc main.rs -o cli-demo
./cli-demo ok
echo $?
./cli-demo missing
echo $?
./cli-demo bad
echo $?预期输出
accepted: ok
0
error: requested resource was not found
3
error: input value is invalid
4不同 shell 对 stderr 与 stdout 的显示顺序可能略有差异,但每次执行后的退出码应分别为 0、3、4。
让脚本只依赖稳定接口
调用方应优先判断退出码,而不是匹配错误文本。例如下面脚本只关心“资源不存在”这一类失败:
./cli-demo missing
code=$?
if [ "$code" -eq 3 ]; then
echo "resource missing; create it before retrying"
fi预期输出
error: requested resource was not found
resource missing; create it before retrying错误文案可以随着可读性要求改进,但退出码一旦被外部脚本使用,就应像命令参数一样谨慎变更。如果确实要调整含义,最好在版本说明中明确兼容性影响。
测试时同时验证文本和退出码
CLI 测试至少要覆盖成功、参数错误和关键业务失败。测试重点不是把每个内部错误枚举都暴露出去,而是确认外部可观察行为稳定:成功走 stdout 且返回 0,失败走 stderr 且返回预定非零值。
对于机器需要消费的复杂错误信息,可以增加 --json 等显式机器输出模式;普通交互模式仍应保持短、可读,并避免打印实现细节、堆栈或敏感数据。