命令行接口
命令行接口（Command-Line Interface，CLI）是程序通过命令、参数、输入输出流和退出状态与调用者交互的接口。调用者既可能是终端前的人，也可能是 Shell 脚本、构建任务或另一个程序。
设计 CLI，不能只考虑怎样把功能运行起来。用户需要知道命令怎么用、失败后怎么改；脚本需要稳定的数据格式和明确的成功条件。参数、输出与失败行为共同构成接口，修改它们也可能破坏已有调用。
1. 面试核心
先记住这几条，再读正文- 好的 CLI 应当容易发现用法、行为一致，并能可靠地用于自动化。帮助信息、参数校验、输出格式和失败处理需要共同设计，不能只罗列几个方便交互的功能。卡 · 参数与帮助信息
- 参数负责说明操作对象与选项，输入流负责传递内容。明确参数含义、默认值与校验规则，让路径中的空格、以
-开头的文件名等情况也有确定的处理方式。卡 · 参数与帮助信息 - 标准输出传递结果，标准错误传递诊断信息，这样进度或报错不会破坏下一条命令读取的数据；调用者仍可以主动合并两种输出。卡 · 标准输入输出
- 退出码传递状态，错误信息解释原因。写出错误信息但仍返回成功，会让自动化继续执行；反过来，只返回非零值也不足以帮助人定位问题。卡 · 退出状态与错误信息
- 自动化需要无需临时询问、输出格式稳定、运行边界明确。交互提示、颜色和进度展示应根据场景调整，不能要求无人值守的任务一直等用户输入。
2. 参数与帮助信息
参数接口应让调用者看得出“处理什么”和“怎样处理”。位置参数按出现的位置表达含义，例如输入文件；选项通过名称表达配置，例如 --format json。名称相近的选项应保持一致的含义，默认行为也要写进帮助信息。
以统计文本行数的 linecount.py 为例：
python3 linecount.py --format json "input data.txt"
这里的 input data.txt 是一个文件路径，--format json 选择 JSON 输出。双引号由 Shell 处理，使含空格的路径作为一个参数传给程序；程序实际收到的路径不包含这对引号。如果不加引号，Shell 会把它拆成两个参数，参数解析器便无法按一个文件处理。
选项结束标记 -- 表示后续内容按位置参数解释。支持这一约定的程序可以接受以 - 开头的文件名，例如：
python3 linecount.py -- -sample.txt
-- 防止 -sample.txt 被解释为选项。它属于参数解析规则，不会改变文件路径本身。下面的示例另外约定单个 - 表示标准输入；若文件名恰好就是 -，可用 ./- 指明文件路径。
帮助信息至少应说明用途、参数与默认值、输入输出格式，并给出一两个能直接照着执行的例子。--help 应能独立显示帮助，--version 应能独立显示版本，不应为了显示这些信息先联网或等待业务输入。
校验也应发生在产生副作用之前。选项拼错、必需参数缺失或选项值不在允许范围内时，直接指出问题，避免静默忽略。涉及配置文件、环境变量和命令行参数时，还要明确它们的覆盖顺序，让同一次调用可以被解释和复现。
3. 标准输入输出
程序启动时通常可以使用三条标准流。在 Unix 类系统中，它们分别对应文件描述符 0、1、2：
| 标准流 | 名称 | CLI 中的主要用途 |
|---|---|---|
| 标准输入 | stdin | 接收要处理的内容 |
| 标准输出 | stdout | 返回结果，供人阅读或交给下一个程序 |
| 标准错误 | stderr | 报告错误、警告和进度等诊断信息 |
它们不固定连接到键盘和屏幕。Shell 可以把文件连接到标准输入，把输出写入文件，也可以用管道把一个程序的标准输出接到另一个程序的标准输入。
假设 linecount.py --format json 成功时只输出 {"lines": 2}，下游就可以直接解析 JSON。如果它先在标准输出打印一行“正在读取”，下游读到的便不再是一个合法的 JSON 文档。进度放在标准错误，结果放在标准输出，就能避免这种干扰。
python3 linecount.py --format json "input data.txt" > result.json 2> error.log
成功时 result.json 保存结果，error.log 为空。文件不存在时，下面的实现不会输出结果，原因写入 error.log，并返回非零退出码。重定向会先由 Shell 创建或截断目标文件，因此不能仅凭 result.json 存在就判断命令成功；具体规则见 Linux 常用命令与文件权限。
面向机器的输出格式需要有稳定的字段、类型和含义。可以用 --format json 明确选择它，不让终端宽度、颜色、语言或进度条改变数据。标准错误也不是秘密存储位置，脚本和日志系统同样可能保存它，错误信息不应直接暴露口令或令牌。
4. 退出状态与错误信息
退出码是程序结束时交给调用者的状态值。Shell 通常把 0 当作成功，把非零值当作未成功；具体非零值的含义由工具定义，不能假定所有工具都用相同的错误分类。
本文的行数统计工具采用以下约定：
| 退出码 | 含义 | 对应行为 |
|---|---|---|
0 | 正常完成，包括显示帮助或版本 | 输出结果或所请求的信息 |
1 | 输入读取失败 | 向标准错误说明文件或读取问题 |
2 | 命令用法错误 | 参数解析器输出用法与参数错误 |
空文件的行数是 0，但这次统计仍然成功，退出码也应为 0。结果值和退出码表达的是不同信息，不能把“没有数据”一律当成程序故障。其他工具还可能把某些非零值用于正常业务结果，例如搜索未匹配；脚本应按工具文档判断。
错误信息应说明哪一步失败、相关对象是什么，以及调用者可以检查什么。文件不存在时指出路径，比只写“执行失败”更有用；参数值错误时列出允许值，比向用户展示内部异常堆栈更有帮助。未预料的内部错误仍需要可追踪的诊断，不能为了界面整洁而吞掉。
管道还带来一层状态组合。Bash 默认使用最后一条命令的退出状态，所以前面的程序失败，后面的 cat 正常结束，整个管道也可能返回 0。脚本需要检测前段失败时，可以启用 Bash 的 set -o pipefail；这时管道返回最右侧非零状态，全部成功才返回 0。它改变的是 Shell 的状态判断，不会撤销已产生的文件或其他副作用。
5. 一个可组合的最小实现
下面用 Python 3.12 实现行数统计。保存为 linecount.py：输入文件按 UTF-8 读取，不传文件或传 - 时读取标准输入；最后一行没有换行符，也计作一行。空输入计作零行。
import argparse
import json
import sys
from contextlib import nullcontext
def main():
parser = argparse.ArgumentParser(
description="Count text lines from a UTF-8 file or stdin.",
allow_abbrev=False,
)
parser.add_argument("file", nargs="?", default="-",
help="input path; '-' or omitted means stdin")
parser.add_argument("--format", choices=("text", "json"), default="text",
help="output format (default: text)")
parser.add_argument("--version", action="version", version="linecount 1.0")
args = parser.parse_args()
try:
source = (nullcontext(sys.stdin) if args.file == "-"
else open(args.file, encoding="utf-8"))
with source as stream:
count = sum(1 for _ in stream)
except (OSError, UnicodeError) as error:
print(f"linecount: cannot read {args.file!r}: {error}", file=sys.stderr)
return 1
result = json.dumps({"lines": count}) if args.format == "json" else str(count)
print(result)
return 0
if __name__ == "__main__":
raise SystemExit(main())
参数解析由 argparse 完成，未知选项和不合法的 --format 值会得到退出码 2。allow_abbrev=False 禁止把长选项缩写为前缀，避免以后新增选项时改变既有缩写的含义。输入全部读完后才输出计数，所以读取失败不会留下一个看起来完整的统计结果。
nullcontext(sys.stdin) 允许两种输入使用同一段统计逻辑，同时不由这段代码关闭调用环境提供的标准输入。文件输入由 with 负责关闭。标准输入的文本编码遵从 Python 运行环境，自动化调用应明确输入编码和环境配置；这里的 UTF-8 文件约定不会自动改写 sys.stdin 的编码。
在 Bash 中可以直接组合两条命令：
printf 'alpha\nbeta\n' | python3 linecount.py --format json
输出为 {"lines": 2}，标准错误为空，统计程序返回 0。把 --format json 改成 --format xml，则用法错误进入标准错误，统计程序返回 2。下游程序因此既能读取结果，也能根据状态决定是否继续。
这个示例只负责参数解析与完整读取后的计数。网络超时、取消、输出端提前关闭等行为不在实现范围内；真实工具一旦涉及这些场景，需要为它们明确错误与清理规则。
6. 交互与自动化
自动化接口应允许调用者提前给齐所需信息，并在无法完成时结束，而不是突然要求人工回答。交互式选择器适合终端操作，但构建任务或管道不一定有可供询问的终端；即使有终端，也不能据此假定调用者愿意等待确认。
可以提供明确的非交互模式，缺少必需信息时返回错误。会修改或删除资源的命令，应让用户看清操作对象，按操作风险设计确认与预演；允许脚本显式选择行为，也要避免把所有保护都藏在一个含义不清的开关里。只读的行数统计没有这类确认需要。
长期运行的工具还应约定超时、取消和资源清理。用户中断任务后，需要停止新工作、收尾或取消未完成操作，并清理自己创建的临时资源；收到信号与实际退出的区别见进程管理与信号。命令失败也不等于外部操作一定没有发生，例如远程写入完成后响应丢失，重试前还需要判断操作是否可重复。
兼容性同样属于接口设计。选项名称、默认值、JSON 字段和退出码一旦被脚本使用，就不能随意改变含义。增加更清楚的帮助信息通常容易兼容；把原本的 JSON 对象改成数组，即使人看起来差不多，也会让已有解析代码失败。
7 · 面试题卡片
本页题目与参考回答
7.1 一个好的 CLI 应该具备哪些特点？
考察重点：同时考虑终端用户和程序调用者，说明参数、结果与失败行为之间的关系。
相关内容：参数与帮助信息、标准输入输出、退出状态与错误信息、交互与自动化。
参考回答
**好的 CLI 应当容易理解、行为可预测，并能可靠地被脚本组合。**需要从完整的一次调用说明设计：
- 参数名称和默认值一致，帮助信息说明用法与例子，错误参数在执行前就被发现。
- 结果进入标准输出，诊断进入标准错误；提供稳定的机器可读格式，避免进度和颜色干扰解析。
- 用退出码说明状态，用错误信息解释原因，不能打印失败信息却仍报告成功。
- 自动化可以提前提供所需配置，缺少信息时明确失败；长任务支持有边界的超时、取消和清理。
- 维护已经公开的参数、输出和退出状态约定，让升级不会悄悄破坏现有脚本。
7.2 路径含空格或以减号开头时，命令行参数怎样处理？
考察重点：Shell 分词与程序参数解析的区别，选项结束标记的作用。
相关内容：参数与帮助信息。
参考回答
**含空格的路径需要通过 Shell 引号等方式保留为一个参数；以减号开头的路径可以在支持该约定的工具中放到 -- 后面。**例如 "input data.txt" 防止 Shell 按空格拆分，-- -sample.txt 防止解析器把文件名当作选项。
Shell 去掉用于分组的引号后再传递参数；-- 则由程序的参数解析器处理。单个 - 是否代表标准输入，要查工具自身的约定，不能当作所有程序共有的规则。
7.3 为什么 JSON 结果和进度信息不应混在标准输出中？
考察重点：数据输出与诊断输出的分工，以及管道的默认连接方式。
相关内容：标准输入输出。
参考回答
**额外的进度文本会破坏 JSON 文档，使下游无法按约定解析结果。**标准输出只写结果，标准错误写进度与诊断，调用者便可以分别重定向它们。
普通管道 | 连接前一个程序的标准输出与后一个程序的标准输入，默认不会同时传递标准错误。调用者可以显式合并输出，但应知道合并后不再保证得到纯 JSON。
7.4 程序已经打印报错，为什么脚本仍可能判断成功？
考察重点：退出码与错误文本的独立性，以及 Bash 对管道状态的组合规则。
相关内容：退出状态与错误信息。
参考回答
**脚本通常依据退出状态判断成功，不会自动分析报错文本。**程序只打印错误却返回 0，调用者就仍会收到成功状态。
还有一种情况是程序本身已经返回非零值，但 Bash 默认只取管道最后一条命令的状态，后段成功掩盖了前段失败。需要检查整条管道时可启用 set -o pipefail；同时还要正确处理失败前已经产生的输出和副作用。
8. 参考资料
- Python 3.12：argparse
- Python 3.12：sys.stdin、sys.stdout、sys.stderr 与 sys.exit
- POSIX：Utility Conventions
- Bash Reference Manual：Pipelines
来源：Coding 101 原文 · 免费阅读，引用请保留出处。内容使用说明