Rust / 系统课时

确定工具边界

确定工具边界

命令行工具在写核心功能前,先要把“什么算合法输入、什么写到标准输出、失败时返回什么”定成稳定契约。本节用一个最小 Rust CLI 明确子命令、参数、标准输出与标准错误、退出码和异常边界,让后续实现可以围绕可测试接口演进。

学习目标

  • 为命令行工具定义清晰的输入、输出和子命令边界
  • 区分 stdout 与 stderr,并设计稳定的退出码
  • 把用户可预期错误与程序缺陷分开处理

先写清命令契约

示例工具名为 textstat,只提供两个子命令:count <PATH> 统计文本行数,version 输出版本。边界越小,后续越容易测试,也越不容易让参数含义互相冲突。

输入契约可以先固定为:count 必须且只能接收一个 UTF-8 文本文件路径;version 不接收额外参数。成功时,机器可消费的数据写入 stdout;用法错误和文件读取错误写入 stderr。

退出码也要成为接口的一部分:

退出码 含义
0 命令成功完成
1 未分类的内部失败
2 子命令或参数不合法
3 输入文件无法读取

把边界直接编码进程序

下面的实现只使用标准库,重点不是参数解析框架,而是把命令边界明确写出来。预期内的用户错误不触发 panic,而是输出简短诊断并返回稳定退出码。

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

用成功和失败各跑一次,就能同时验证输出通道与退出码:

bash
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' "$?"

预期输出:

text
2
success_exit=0
unknown subcommand: missing
usage: textstat <count <PATH>|version>
error_exit=2

终端通常会把 stdout 与 stderr 一起显示,所以示例中看起来在同一块区域;在脚本重定向时,两条通道仍可被独立处理。

让异常处理停在正确边界

命令行边界应把“用户能修正的错误”转换成稳定消息和退出码,例如路径不存在、参数缺失或子命令拼错。此类错误不应打印 Rust panic 堆栈,否则既影响脚本消费,也把实现细节泄漏给普通用户。

真正的程序缺陷则不同,例如违反内部不变量或理论上不可能出现的状态。它们应该被开发期测试尽早暴露,而不是伪装成“参数错误”。如果工具需要更丰富的诊断,可以增加 --verbose 或日志模式,但默认输出仍应保持简洁稳定。

命令行工具从输入到输出与退出码的边界流程

用验收条件守住边界

实现新功能时,不要只验收“命令能跑”。至少检查合法命令的 stdout 是否只包含承诺的数据、非法输入是否写入 stderr、退出码是否稳定,以及脚本在重定向输出后仍能可靠判断成功或失败。

边界一旦公开,就应把它当作兼容性契约维护。新增子命令可以扩展能力,但不要随意改变既有参数含义、输出格式或退出码,否则调用它的脚本会在没有编译错误的情况下悄悄失效。

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

目录与阅读设置

阅读设置

17

记录一个想法

确定工具边界

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

登录哪都通