在我的前一篇文章中, ,我们研究了如何从头开始构建一个CLI工具。现在,让我们采取下一步 - 如何使它变得好? 最终,关键在于易于使用。 一个设计好的CLI对用户来说是直观的,可预测的和高效的。 掌握命令行艺术:开发强大的工具的最终指南 掌握命令行艺术:开发强大的工具的最终指南 为了示范,我们将使用 ,但这些原则适用于几乎任何您可能使用的 CLI 框架。 点击 Python 图书馆 参数 大多数CLI工具都接受用户的输入,在大多数情况下,这个输入不是互动的,它以用户的输入形式出现。 这决定了工具是如何运行的。 parameters 例如,该 命令至少需要两个参数: cp 
 
 
 通往要复制的文件或目录的路径,以及 通往目的地的道路。 它还可以接受可选参数,如 它可以实现 verbose 输出。 -v 一般来说,有两种类型的参数: 和 在大多数 CLI 库中,所需参数被称为 (或位置参数),并称为可选参数 . required optional arguments options 积极论点 正如名字所暗示的, 用户以特定的顺序提供值,而工具则相应地解释它们。 positional arguments 例如,如果 命令预计两个定位论点 - 和 用户将其称为: cp 来源 目的地 cp source destination
 即使您的工具需要输入,也常常是繁琐的(和不必要的),让用户手动指定每个值。 . if you can provide a sensible default, make it an option instead of an argument 例如,a 参数可以偏移到 强迫用户记住位置并始终传递信息不会增加价值 - 它只是增加摩擦。 --log-level info 多种论点 有时,一个工具可能需要接受 一个单一的参数. 一个常见的例子是指定多个源文件来复制到一个目标目录. 这允许用户运行一个命令而不是多个: multiple values cp source1 source2 destination
 有几个警告 - 通常, 您的代码(而不是参数解析器)必须处理额外的验证和逻辑。 only one argument 选择 允许用户按名称指定参数,通常在表格中 如果用户没有提供一个选项,该工具会使用其默认值。 Options --option value 例如: --log-level debug
 一个特殊类型的选项是旗帜 - 它不需要一个值. 旗帜的存在只会改变一种行为,例如允许无语的输出: --verbose
 选项名称应该是 用户可以很容易地理解他们的目的。 clear and descriptive 实施示例: @click.command()
@click.option('--verbose', is_flag=True)
@click.option('--log-level', default="info")
@click.argument('srcs', nargs=-1)
@click.argument('dst')
def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str):
   ...
 现在,该工具可以用几种方式调用: cp --verbose --log-level trace source1 source2 destination
cp source destination
 短选项 到目前为止,我们已经使用了长的选项名称,这些名称是脚本的理想选择,因为它们是自我解释的,一眼就能理解。 然而,对于快速、一次性命令,用户往往更喜欢 像 相反, 在引入短表格时要有选择性. 并非每个选项都需要一个。 如果你的工具有许多选项,你会很快用完直观的字母 - 特别是因为多个选项可能从同一个开始。 . short options -v --verbose frequently used options 例子: @click.command()
@click.option('-v', '--verbose', is_flag=True)
@click.option('--log-level', default="info")
@click.argument('srcs', nargs=-1)
@click.argument('dst')
def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str):
   ...
 现在这两种形式都起作用: cp -v source destination
cp --verbose source destination
 验证用户输入并快速失败 一个强大的 CLI 工具应该 并通过一个清晰、可操作的消息失败.大多数CLI框架支持此模式。 validate user input early 例如,Click 可以自动执行有效的日志级别和路径参数: @click.command()
@click.option('-v', '--verbose', is_flag=True)
@click.option('--log-level', default="info", type=click.Choice(["debug", "info", "error"]))
@click.argument('srcs', nargs=-1, type=click.Path())
@click.argument('dst', type=click.Path())
def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str):
   ...
 However, you may still need  在我们的 例子: custom logic copy 
 
 
 如果有一个源,目的地可能是文件或目录。 如果有多个源,目的地必须是一个目录,否则文件可能会意外地相互重写。 一般的 CLI 库不会自动处理此类案例,因此这种验证必须存在于您的代码中。 帮助信息 一个好的工具总是提供一个好的工具 . help message 用户应该能够运行类似的 要看: --help 
 
 
 
 哪些参数可用 他们的意义 接受的类型或值(例如,有效的日志级别) 一个清晰的帮助消息可以节省时间,减少错误,并提高用户对工具的信任。 跟踪你的生态系统模式 最后,伟大的CLI工具感觉 研究你的环境中的其他工具,并遵循他们的惯例 - 特别是对于 . native naming options and arguments 例如,在Unix世界中,诸如 , ,和 全部使用 和 作为立场论点,与 总是先行 . cp mv rsync source destination source destination 常见的名称和熟悉的选项字母( 对于口语, 为了回归, 干燥的跑步, 帮助)让您的工具无缝融入用户的工作流程。 -v -r -n -h/--help 当你的工具感觉像是生态系统的自然部分时,用户将更有可能采用它 - 并享受使用它。 其他方面 除了参数和论点之外,还有几个其他因素区分一个 这些方面影响您的工具如何与脚本集成,用户如何调试问题,以及它如何容易融入更大的工作流程。 好 出口代码 每个程序返回一个 此代码允许呼叫者知道程序是否成功或失败。 exit code 根据公约: 
 
 
 0 意味着成功 任何非零值表示错误 虽然出口代码没有通用标准,但至少使用 . exit with a non-zero code on any error 为了更好的一致性,考虑遵循从 这些在Unix世界中被广泛认可。 先进的 Bash-Script 指南 你也应该 把它们纳入到 当用户或自动化系统了解输出代码3的含义时,他们可以更智能地处理错误(例如,重置,跳过或警报)。 document your exit codes --help 斯特拉克 vs 斯特拉克 一个良好的 CLI 工具可以区分其两个标准输出流: 
 
 
 STDOUT - 对于正常的预期输出 STDERR - 对于错误、警告或诊断信息 这种分离允许用户和脚本独立处理每个流,例如,用户可以将正常输出重定向到一个文件,同时在控制台上保持错误消息的可见性: mytool > output.txt
 或删除错误: mytool 2>/dev/null
 如果您的工具将数据和错误都写入STDOUT,用户将需要手动过滤输出 - 这很脆弱。 特别是如果您的工具的输出被其他程序消耗,保持STDOUT的清洁性和可预测性至关重要。 输出格式 如果您的工具生成可能被其他工具或脚本消耗的数据,则支持 JSON 或 YAML 等格式。 machine-readable output 例如: mytool --output json
 这使得自动化变得更容易 - 其他工具可以使用标准解析器,而不是依赖于脆弱的字符串解析器,每当间隔、对齐或点缀变化时就会被打破。 但是,不要牺牲人类的可读性. 许多用户仍然会互动地运行您的工具. 最好的方法是: 
 
 
 默认到人体可读的输出(零格式文本) 提供一个旗帜(例如 --json 或 --format 若要支持多个格式)用于结构化输出 一些CLI工具还提供 ,在写到终端时发送漂亮的文本,但在输入另一个流程时发送JSON - 类似于如何 或 行事 auto-detection kubectl gh 错误消息 一个好的错误信息应该是: 
 
 
 
 清晰 - 说明发生了什么错误 可操作 - 建议如何修复它 一致 - 使用相同的色调和结构 坏例子: Error: failed
 更好的例子: Error: Could not open file '/tmp/input.txt' — file not found.
Hint: Verify that the path is correct and you have read permissions.
 良好的错误处理可以节省用户的时间,并帮助他们建立对您的工具的信任。 传说与 Verbosity 用户欣赏对他们看到多少信息的控制。 
 
 
 
 安静,最小输出 --verbose 用于详细的信息  for developer-level tracing --debug 设计您的日志级别,以便用户可以为其背景选择合适的信息量。 当与适当的输出代码相结合时,这些级别使调试和自动化更顺利。 响应性和性能 如果您的 CLI 执行重型操作,请考虑提供 或 例如: progress indicators spinners Downloading files... 45% complete
 同时,当工具在非交互模式下运行时(例如作为脚本的一部分)避免不必要的动画或输出。 结论 构建一个 CLI 工具相对简单。  one — that’s the real craft. A good command-line tool feels natural, behaves predictably, and quietly disappears into the user’s workflow. It doesn’t force users to adapt to  它适应了用户已经工作的方式。 good 它 在这篇文章中,我们研究了这项经验的贡献: 
 
 
 
 
 
 
 清晰和一致的参数,平衡简单性和灵活性 传达成功或失败的有意义的退出代码 正确使用STDOUT和STDERR来将数据与诊断分开 可读和结构化的输出格式,适用于人类和机器 有用的错误信息和可预测的行为 遵守你的生态系统的惯例,让你的工具从一开始就感觉熟悉。 最终,最好的 CLI 工具都有一个共同点:它们 他们快速开始,快速失败,清楚地解释自己,并无缝集成到更大的系统和脚本中。 respect the user’s time 如果你记住这些原则 - 清晰度,一致性和对用户的同情 - 你的 CLI 工具不仅会 ;它将是一个乐趣使用。 工作

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Read My Stories

該音頻是用故事的原始語言製作的！

如何设计一个开发人员实际上喜欢使用的CLI工具

About Author

註釋

標籤

这篇文章刊登在

Related Stories

比特币 UTXO 模型，为独特的生态系统提供动力

看不见的层面：为什么用户访谈是不可替代的资产

如何将您的工作流程提高 10 倍：17 个必备应用程序

HackerNoon Decoded: The Top 10 Countries Where HackerNoon Is the Most Active

比特币 UTXO 模型，为独特的生态系统提供动力

看不见的层面：为什么用户访谈是不可替代的资产

如何将您的工作流程提高 10 倍：17 个必备应用程序

HackerNoon Decoded: The Top 10 Countries Where HackerNoon Is the Most Active

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps