Rust / 系统课时
确定工具边界
确定工具边界
命令行工具在写核心功能前,先要把“什么算合法输入、什么写到标准输出、失败时返回什么”定成稳定契约。本节用一个最小 Rust CLI 明确子命令、参数、标准输出与标准错误、退出码和异常边界,让后续实现可以围绕可测试接口演进。
学习目标
- 为命令行工具定义清晰的输入、输出和子命令边界
- 区分
stdout与stderr,并设计稳定的退出码 - 把用户可预期错误与程序缺陷分开处理
先写清命令契约
示例工具名为 textstat,只提供两个子命令:count <PATH> 统计文本行数,version 输出版本。边界越小,后续越容易测试,也越不容易让参数含义互相冲突。
输入契约可以先固定为:count 必须且只能接收一个 UTF-8 文本文件路径;version 不接收额外参数。成功时,机器可消费的数据写入 stdout;用法错误和文件读取错误写入 stderr。
退出码也要成为接口的一部分:
| 退出码 | 含义 |
|---|---|
0 |
命令成功完成 |
1 |
未分类的内部失败 |
2 |
子命令或参数不合法 |
3 |
输入文件无法读取 |
把边界直接编码进程序
下面的实现只使用标准库,重点不是参数解析框架,而是把命令边界明确写出来。预期内的用户错误不触发 panic,而是输出简短诊断并返回稳定退出码。
use std::{env, fs, process::ExitCode};
fn usage() -> &'static str {
"usage: textstat <count <PATH>|version>"
}
fn main() -> ExitCode {
let mut args = env::args().skip(1);
match args.next().as_deref() {
Some("version") if args.next().is_none() => {
println!("textstat 0.1.0");
ExitCode::SUCCESS
}
Some("count") => {
let Some(path) = args.next() else {
eprintln!("missing PATH\n{}", usage());
return ExitCode::from(2);
};
if args.next().is_some() {
eprintln!("too many arguments\n{}", usage());
return ExitCode::from(2);
}
match fs::read_to_string(&path) {
Ok(text) => {
println!("{}", text.lines().count());
ExitCode::SUCCESS
}
Err(err) => {
eprintln!("cannot read {path}: {err}");
ExitCode::from(3)
}
}
}
Some(command) => {
eprintln!("unknown subcommand: {command}\n{}", usage());
ExitCode::from(2)
}
None => {
eprintln!("{}", usage());
ExitCode::from(2)
}
}
}预期结果:将代码保存为 src/main.rs 后,合法的 count 命令输出行数并返回 0,未知子命令写入诊断并返回 2,文件读取失败返回 3。
用成功和失败各跑一次,就能同时验证输出通道与退出码:
printf 'alpha\nbeta\n' > sample.txt
cargo run --quiet -- count sample.txt
printf 'success_exit=%s\n' "$?"
cargo run --quiet -- missing
printf 'error_exit=%s\n' "$?"预期输出:
2
success_exit=0
unknown subcommand: missing
usage: textstat <count <PATH>|version>
error_exit=2终端通常会把 stdout 与 stderr 一起显示,所以示例中看起来在同一块区域;在脚本重定向时,两条通道仍可被独立处理。
让异常处理停在正确边界
命令行边界应把“用户能修正的错误”转换成稳定消息和退出码,例如路径不存在、参数缺失或子命令拼错。此类错误不应打印 Rust panic 堆栈,否则既影响脚本消费,也把实现细节泄漏给普通用户。
真正的程序缺陷则不同,例如违反内部不变量或理论上不可能出现的状态。它们应该被开发期测试尽早暴露,而不是伪装成“参数错误”。如果工具需要更丰富的诊断,可以增加 --verbose 或日志模式,但默认输出仍应保持简洁稳定。

用验收条件守住边界
实现新功能时,不要只验收“命令能跑”。至少检查合法命令的 stdout 是否只包含承诺的数据、非法输入是否写入 stderr、退出码是否稳定,以及脚本在重定向输出后仍能可靠判断成功或失败。
边界一旦公开,就应把它当作兼容性契约维护。新增子命令可以扩展能力,但不要随意改变既有参数含义、输出格式或退出码,否则调用它的脚本会在没有编译错误的情况下悄悄失效。