第 3 章 · 02 设计合理的 CLI 接口

文档摘要

第 3 章 · 02 设计合理的 CLI 接口本节摘要: 参数解析解决了「怎么接参数」,这一节解决「怎么把接口设计得合理」——两者不是一回事。一个好 CLI 的接口要遵循几条不成文的约定: 短选项 -v 与长选项 --verbose 成对出现、必选参数缺失时必须报错而非静默用默认值、 / 在任何情况下都要有效(哪怕其他参数全写错)、退出码要有清晰的语义(0 成功,非零按错误类型编码)。这些细节看似琐碎,却决定了你的工具是「顺手」还是「别扭」,也决定了它能不能被脚本可靠地调用。本节导读这些约定,并呼应姊妹篇《Linux 命令实战》第 1 章的「退出码」与「求助四件套」。

第 3 章 · 02 设计合理的 CLI 接口

本节摘要: 参数解析解决了「怎么接参数」,这一节解决「怎么把接口设计得合理」——两者不是一回事。一个好 CLI 的接口要遵循几条不成文的约定: 短选项 -v 与长选项 --verbose 成对出现、必选参数缺失时必须报错而非静默用默认值、-h/--help 在任何情况下都要有效(哪怕其他参数全写错)、退出码要有清晰的语义(0 成功,非零按错误类型编码)。这些细节看似琐碎,却决定了你的工具是「顺手」还是「别扭」,也决定了它能不能被脚本可靠地调用。本节导读这些约定,并呼应姊妹篇《Linux 命令实战》第 1 章的「退出码」与「求助四件套」。

内容来源: 基于原索引「Build your own X」Command-Line Tool 域相关条目整理的导读,原始教程为外部资源(如「Command Line Interface Guidelines」「Build your own grep」等)。

学习目标

阅读完本节,你应当能够:

解释短选项与长选项为什么要成对提供(-v 与 --verbose 指向同一个开关),并知道哪些场景可以只给其一。
说清「必选参数缺失」的正确处理: 报错并打印用法,而不是静默退回默认值。
理解为什么 -h/--help 必须在任何情况下都有效——哪怕其他参数写错,help 也要能跑出来。
设计一套清晰的退出码语义: 0 成功、2 用法错误、126/127 命令问题、其他非零表示各类失败。
列出 CLI 的「求助四件套」(--help、--version、man 手册页、用法提示),呼应《Linux 命令》第 1 章。
判断一个 CLI 接口设计得好不好,能挑出常见反例(静默失败、退出码混乱、help 报错)。

一、学习价值: 为什么「能解析」不等于「设计得好」

上一节你学会了怎么把 argv 解析成选项和位置参数。但「能解析」只是技术门槛,「设计得好」是另一门功夫——它关乎用户体验和可脚本化。

举个反例。某工具要求用户输入源文件和目标文件,但用户漏了目标文件时,工具不报错,而是「静默把源文件当目标」覆盖掉——用户半天后发现文件没了,根本不知道是哪步出的问题。这就是典型的「接口设计烂」: 必选参数缺失,本该立刻报错退出,却选择了最危险的「静默处理」。

再举个反例。某工具失败时一律返回退出码 0(因为「程序跑完了嘛」),结果在脚本里 tool && next-step 永远会执行 next-step,哪怕 tool 已经失败——脚本作者被坑得体无完肤。这就是「退出码语义不清」的代价。

好 CLI 的接口设计,核心是两条原则:

可脚本化优先: 任何操作都能用命令行完成,退出码要能让脚本判断成败。
约定优于配置: 遵循 Unix 半个世纪沉淀下来的约定(-h 永远有效、0 表示成功、必选参数报错),用户无需看文档就能猜对用法。

这些约定不是某个人定的,而是无数工具协作中「自然选择」出来的——遵循它们,你的工具就能无缝融入 Unix 生态(被管道串、被脚本调、被 shell 补全);违背它们,你的工具就是个「外来物种」,用户用着别扭,脚本调着坑。

关键概念: 「设计得好」的判断标准不是「功能多」,而是「用户猜对用法的概率高」。一个好 CLI,用户不看文档也能猜个八九不离十——因为它们都遵循同一套约定。这正是姊妹篇《Linux 命令》第 1 章「求助四件套」存在的意义。

值得留意的是,这套约定有「GNU 风格」和「BSD 风格」两个流派,你会在不同工具里都碰到。GNU 风格(大多数 Linux 工具)倾向于「短选项 + 长选项成对」、支持 --option=value 写法、参数顺序宽松;BSD 风格(传统 Unix 工具如 ps、tar)更简朴,有时只给短选项、参数顺序更严格(比如 tar -cvf archive.tar dir 里 f 后必须紧跟文件名)。你造工具时,优先遵循 GNU 风格(它对用户更友好),但读别人的代码时要能识别两种风格——这样才不会在 ps aux(BSD 风格,无横线)和 ps -aux(GNU 风格)的区别上犯迷糊。

💡 学习建议: 学接口设计最快的办法不是读规范,而是「用」——挑五个你常用的成熟工具(ls、grep、git、docker、curl),故意敲错参数(漏掉必选、敲错选项名、加 -h),观察它们怎么报错、怎么提示用法。你会发现它们的行为高度一致(都遵循本章的四条约定),这种「一致性」就是约定的力量。把这些观察记下来,你造工具时就有现成的模板可抄。

二、子系统拆解: 四条核心约定

约定一: 短选项与长选项成对提供

一个好 CLI 通常给每个常用选项同时提供短形式和长形式:


-v, --verbose    详细输出
-q, --quiet      安静模式
-o, --output     输出文件
-n, --name       名称

两种形式的分工在上一节讲过: 短选项(-v)适合交互时手敲,省事;长选项(--verbose)适合写在脚本里,自文档化。成对提供,就是兼顾两种使用场景。

例外: 极少数选项只给长形式——通常是那种「很少在命令行手敲、基本只写在配置或脚本里」的选项,比如 --no-color、--dry-run。反过来,只给短形式不给长形式是坏味道,意味着你剥夺了脚本作者的可读性。

💡 学习建议: 短选项的字母选择有惯例——-v 几乎总是 verbose 或 version、-h 总是 help、-q 总是 quiet、-o 总是 output、-f 总是 force。遵循这些惯例,用户的「肌肉记忆」就能复用,不用重新学。

约定二: 必选参数缺失必须报错

这是接口设计里最重要的一条,也是新手最容易犯的错。必选参数(比如 cp 的源文件和目标文件)缺失时,正确做法是:


$ mycopy a.txt
错误: 缺少目标文件
用法: mycopy <源文件> <目标文件>
运行 mycopy --help 查看完整说明
(退出码 2)

错误做法有两种,都很致命:

静默用默认值: 漏了目标文件就默认复制到 output.txt,用户完全不知情,可能覆盖重要文件。
静默不做事: 既不报错也不执行,用户以为成功了,实际什么都没发生。

正确的处理是三件套: 打印错误信息 → 打印用法提示 → 以非零退出码退出(约定用 2 表示「用法错误」)。让用户立刻知道「我敲错了,正确敲法是这样」,而不是埋一个雷等以后爆炸。

必选参数检查有一个更深的原则——「报错早,失败响亮」(fail fast, fail loud)。越早发现问题(在解析阶段就拦下),越能避免后续业务逻辑带着错误的数据往下跑,造成不可预测的后果。一个漏检的目标文件参数,如果没在入口拦住,会被一路传到「打开文件」「写入」等步骤,中途崩在一个莫名其妙的地方,排查极难。入口处的必选参数检查,就是把错误「前置」——这是防御性编程在 CLI 里的具体体现。


# 伪代码: 必选参数检查
def main(argv):
    if len(argv) < 3:
        sys.stderr.write("错误: 缺少参数\n")
        sys.stderr.write("用法: mycopy <源> <目标>\n")
        sys.stderr.write("运行 mycopy --help 查看说明\n")
        exit(2)                    # 2 = 用法错误
    ...

⚠️ 难点预警: 「报错信息要打到哪里」是个细节——错误和用法应该打到 stderr(标准错误流),不是 stdout。因为 stdout 可能被重定向到文件或管道,如果错误信息混进 stdout,下游命令就会把错误信息当数据处理。stdout 只放「正常输出结果」,stderr 放「诊断信息」——这是 Unix 的硬约定。

stdout 与 stderr 分流的实战意义,用个例子最清楚。假设你写 mytool process data.csv > result.csv,正常结果进了 result.csv。如果这时 mytool 报了个警告却打到 stdout,警告就会混进 result.csv,污染数据;但如果警告打到 stderr,它只显示在终端上,结果文件干干净净。这就是「stdout 给数据、stderr 给人看」的分工——它让你的工具能安全地被重定向和管道串联。

约定三: `-h`/`--help` 永远有效

这条约定看起来简单,做起来容易漏。它的完整含义是: 无论用户敲了什么其他参数,只要带了 -h 或 --help,就打印帮助并退出,不报任何错。

考虑这个场景: 用户敲了 mytool --unknown-flag --help,其中 --unknown-flag 是个不存在的选项。坏工具会先报「未知选项 --unknown-flag」然后退出,用户根本看不到 help;好工具会优先响应 --help,先打印帮助,因为「用户想看帮助」这个意图比「他敲了个错选项」更重要。


# 伪代码: help 优先 (先扫一遍 argv 找 -h/--help)
def main(argv):
    if "-h" in argv or "--help" in argv:
        print_help(); exit(0)      # 优先级最高, 任何错误都不挡它
    # 然后才是正常解析 (这时才检查未知选项、必选参数等)
    parse_and_run(argv)

这个细节体现的设计哲学是: 帮助是用户的最后一根稻草。当用户卡住、不知道怎么用时,他敲 --help,工具必须回应——不管他之前敲错了什么。这是「以用户为中心」的接口设计。

实现「help 优先」有一个常见的踩坑点——很多新手把 help 检查放在解析循环的最后(等其他选项都解析完才查 -h),结果中间任何一步报错都会跳过 help。正确做法是先扫一遍 argv,只要发现 -h/--help 就立刻响应,然后再走正常解析流程。这个顺序不能反。

帮助文本本身也要遵循结构。一份好的 --help 输出包含四块:


mytool 1.2.0 - 一个示例命令行工具           ← 标题 + 版本 + 一句话说明

用法:  mytool [选项] <文件>...               ← 用法行 (Usage)
       mytool <子命令> [选项]

选项:                                        ← 选项列表
  -v, --verbose     详细输出
  -o, --output FILE 输出到文件
  -h, --help        显示帮助并退出
      --version     显示版本并退出

子命令:                                      ← 子命令列表 (如有)
  add     添加任务
  list    列出任务

示例:                                        ← 一两个常见例子
  mytool -v -o result.txt input.txt
  mytool add "买菜"

💡 学习建议: 帮助文本的第一行(用法行)最重要——它应该能让用户在五秒内理解「这个工具怎么用」。把最常见的用法放用法行,细节放下面。别一上来就堆二十行选项,用户会被吓跑。

约定四: 退出码要有清晰语义

退出码(exit code)是 CLI 和脚本之间的「契约」——脚本靠它判断命令成功还是失败。退出码是一个 0 到 255 的整数,Unix 沉淀出了一套通用语义:

退出码	含义	典型场景
0	成功	命令正常完成
1	一般性失败	业务错误(文件找不到、校验失败)
2	用法错误	参数不对、必选参数缺失
126	命令不可执行	文件存在但没执行权限
127	命令未找到	PATH 里找不到这个命令
128+N	被信号 N 杀死	比如被 Ctrl-C 杀(130 = 128+2)

这套约定不是随便定的——它来自 POSIX 标准和 Bash 的行为,《Linux 命令实战》第 1 章详细讲过。你造 CLI 时,应该沿用这套语义,这样脚本作者不用看你的文档就能猜对退出码含义。

最容易踩的坑是「一律返回 0」或「一律返回 1」:

一律返回 0: 脚本里 tool && next 永远执行 next,哪怕 tool 失败——脚本作者被坑。
一律返回 1: 脚本无法区分「参数错」(该修参数)和「业务失败」(该重试)——诊断能力丧失。

好工具会按错误类型编码: 参数错返回 2、文件不存在返回 1、权限问题返回 126、被中断返回 130。这样脚本就能精细处理不同情况。

退出码在脚本里的典型用法是这样的——你写一个部署脚本,要区分「配置错」(该改配置,不该重试)和「网络抖动」(该重试):


# 伪代码: 脚本根据退出码分流处理
mytool deploy config.yaml
case $? in
    0)   echo "部署成功" ;;
    2)   echo "配置错误, 请检查后重跑"; exit 2 ;;      # 不重试
    1)   echo "一般失败, 重试一次"; mytool deploy config.yaml ;;
    130) echo "被用户中断"; exit 130 ;;
esac

如果你的工具不分类型、失败一律返回 1,这个脚本就写不出来——脚本无法知道该重试还是该停下。所以退出码的「类型编码」不是装饰,而是工具与脚本协作的协议。


# 伪代码: 按类型设退出码
def main(argv):
    try:
        opts = parse(argv)         # 解析失败抛 UsageError
        result = run(opts)         # 业务失败抛 AppError
    except UsageError as e:
        sys.stderr.write("用法错误: " + str(e) + "\n")
        return 2
    except FileNotFoundError:
        sys.stderr.write("文件不存在\n")
        return 1
    except PermissionError:
        sys.stderr.write("权限不足\n")
        return 126
    return 0                       # 成功

关键概念: 退出码是「机器读」的,错误信息是「人读」的——两者都要有。错误信息打到 stderr 给人看,退出码返回给脚本判断。两者配合,你的工具才能既对人友好、又对脚本可靠。

求助四件套: 呼应《Linux 命令》第 1 章

姊妹篇《Linux 命令实战》第 1 章讲过「求助四件套」——任何一个合格的 Unix 命令,都应该提供这四种求助途径:

-h / --help: 简短帮助,直接打到终端,五秒内能读完。
--version: 显示版本号,方便用户报告 bug 时附上版本。
man 手册页: 详细手册,通过 man mytool 查看(适合系统级工具,你的小工具可以省略)。
用法提示: 出错时自动打印的「Usage: ...」一行,告诉用户正确敲法。

这四件套不是摆设——它们是 Unix 用户「求救」的标准动作。当用户卡住,他会先敲 --help,不行就 man,再不行就故意敲错参数看用法提示。你的工具把这四件套都备齐了,用户就永远有路可退。

四件套之间还有个分工细节值得留意: --help 是「主动求助」(用户想看),用法提示是「被动提示」(用户犯错时自动出现)。前者要详细完整(列所有选项),后者要简短(只一行,点出最可能的正确敲法)。两者长度不同、触发时机不同,但都指向同一个目标——让用户尽快走出困境。别把出错时的用法提示写成一整页 help,那是用 --help 该干的事。

⚠️ 难点预警: 求助四件套里最容易漏掉的是「用法提示」——很多新手工具只在 --help 时打印用法,而出错时只打印一句干巴巴的「参数错误」。正确的做法是: 出错时除了报错,还要附带一行简短用法提示(比如「用法: mytool <源> <目标>」),让用户不用再敲一次 --help 就能知道正确敲法。这一个小细节,用户体验提升很大。

三、上手第一步: 给工具加一层「合理」的外壳

掌握了四条约定,上手时按这个顺序把它们逐条落实:

第一步: 检查必选参数。在你的工具入口加一段参数数量检查,缺了就报错 + 用法 + 退出码 2。这是收益最高的一步,能避免 80% 的「静默失败」事故。

第二步: 加 -h / --help。写一份结构化的帮助文本(标题 + 用法行 + 选项列表 + 示例),并确保它在任何参数组合下都能跑出来(先扫 argv 找 -h)。

第三步: 整理退出码。把工具里所有 exit(1) 拿出来审视——这个失败是「用法错」(改 2)还是「业务失败」(留 1)还是「权限问题」(改 126)?给每种失败一个对应的退出码。

第四步: 加 --version。从你的构建系统读版本号,--version 时打印出来。这一步看似小,但用户报 bug 时附版本号能省你大量排查时间。

关键概念: 这四步加起来,本质上是把「一个能跑的程序」升级成「一个合格的 Unix 工具」。能跑只是技术门槛,合格是工程标准——后者要求工具遵循生态约定,能被脚本可靠调用、能融入管道链、能让用户猜对用法。这条从「能跑」到「合格」的跃迁,是本章前两节(参数解析 + 接口设计)共同交付的价值。

💡 学习建议: 找三五个你常用的成熟工具(ls --help、grep --help、git --help),仔细看它们的帮助文本结构——你会发现它们都遵循同一套「标题/用法/选项/示例」的布局。模仿它们,你的工具就有专业感。

外部有一篇广为流传的「Command Line Interface Guidelines」(命令行接口设计指南),系统总结了这些约定背后的理由,推荐作为本节的延伸阅读。它不是教程(没有代码),而是「设计哲学」的合集,读完你会对「为什么 Unix 工具都长这样」有更深的理解。

本节要点回顾

短选项与长选项成对提供: -v 和 --verbose 指向同一开关,兼顾手敲省事和脚本可读;只给短形式不给长形式是坏味道。
必选参数缺失必须报错: 三件套——错误信息 + 用法提示 + 退出码 2,绝不静默用默认值或静默不做事。
错误信息打到 stderr: stdout 只放正常结果,stderr 放诊断信息——否则会污染下游管道。
-h/--help 永远有效: 优先响应,哪怕其他参数全错也要先打 help——帮助是用户最后一根稻草。
退出码按错误类型编码: 0 成功、1 一般失败、2 用法错误、126 不可执行、127 未找到、128+N 被信号杀——沿用这套语义,脚本才能精细处理。
求助四件套: --help、--version、man 手册页、用法提示,四者备齐,用户永远有路可退(呼应《Linux 命令》第 1 章)。
可脚本化优先: 接口设计的目标是「让脚本能可靠调用」,退出码清晰、stderr/stdout 分流、--help 永远有效都是为此服务。

第 3 章 · 02 设计合理的 CLI 接口

文档摘要