令人愉悦的 CLI 的 10 条设计原则

November 21, 2022

Design Doc

CLI

原文链接： 10 design principles for delightful CLIs

与既定惯例保持一致 #

自计算机诞生以来，CLI 几乎就已经存在，因此你无需重新发明轮子来创造令人愉悦的体验。

已经有许多既定的约定和指南可用于设计 CLI，例如 Heroku 的 CLI 风格指南和 Microsoft 风格指南。使用你的用户已经熟悉的现存的模式，你可以确保他们很容易习惯你的工具。

构造 help 命令 #

在 CLI 中添加 --help 命令可为用户提供重要的文档。它让新用户发现所有可用的命令和选项，而更有经验的用户可以在使用 CLI 的整个过程中将其作为参考。

为了帮助你的用户完成他们的任务，--help 部分应该提供一个完整的命令列表、子命令和任何具有简单描述的短命令。

你还应该确保你的用户可以在任何特定命令之后运行 --help 标志，以快速查看他们可以用来处理该命令的完整语法（用法、参数和选项）。

可视化执行过程 #

虽然系统状态的可见性是适用于任何界面设计，但在设计 CLI 的纯文本界面时尤其重要。如果没有图形用户界面 (GUI) 来提供即时的视觉反馈，CLI 并不总是能很好地让用户了解幕后发生的事情。

我们建议你使用进度条、旋转器和其他视觉设备来显示正在发生的事情。我们还建议你将长时间运行的任务分解为一系列有意义的步骤，以帮助将系统状态传达给你的用户。

增加执行反馈 #

CLI 并不总是清楚地表明何时发生了操作。对于用户执行的每项操作，你的 CLI 都应提供平等且适当的反应，清楚地突出显示当前系统状态。

例如，在 Forge CLI 中，如果登录用户键入 forge logout，则会显示一条消息，明确指示操作已成功。

可读的错误信息 #

错误是意料之中的，甚至（我们敢说）是使用任何 CLI 的重要组成部分。

在测试 Forge CLI 时，我们观察到错误是阻止开发人员构建其应用程序的主要障碍之一。

我们的 CLI 有时会吐出错误消息，正如我们的一位工程师曾描述的那样，这些消息是“人类无法阅读的”。这些是直接来自创建它的后端系统的错误消息，对试图找出问题所在以及如何快速从中恢复的用户几乎没有价值。

为了帮助用户尽快回到正轨，你的 CLI 显示的每条错误消息不仅应包含对问题所在的书面描述，还应包含有关如何修复它的建议。你甚至可以包含一个链接以查找有关该错误的更多信息。

提示信息分段，支持粗读 #

虽然在 CLI 中包含你的用户必读的所有文档可能很吸引人，但这可能会使试图快速完成手头工作的用户不知所措。

例如，在 Forge CLI 的可用性测试中，我们观察到许多开发人员经常浏览文本，只寻找与他们的即时需求相关的信息。

为了支持更注重行动的用户，你应该将信息分解成易于理解的块，以便于用户扫描。我们遵循的一般经验法则是，将 CLI 命令附带的任何说明在每个段落中保持不超过 3 个句子（或大约 50-75 个字符）。

你还应该使用文本格式、列表和图标等视觉设备来强调重要信息。我们建议将图标集保持在最低限度。这使每个图标都可以作为有用的寻路元素脱颖而出。

提示下个步骤 #

在使用 CLI 的整个过程中，用户将重复运行相同的命令序列。例如，在 Forge CLI 中，一个常见的顺序是 forge login，然后 forge create。

虽然经验丰富的 CLI 用户会很快熟练地运行相同的命令序列，但 CLI 的新用户和经验不足的用户有时可能需要一些提醒。

通过识别常见的使用模式，你可以聪明地建议用户在每个命令结束时应该采取的下一个最佳步骤，从而减少用户返回参考文档的需要。

选择大于填空 #

当用户在你的 CLI 中执行命令时，他们可能还需要传递一些选项来执行该命令。虽然有经验的 CLI 用户可能会熟练地传递所有必需的信息，但其他用户可能需要一些提示。

你的 CLI 不应抛出错误，而应提示用户输入任何未完成的信息。确保考虑用户提供一些、没有和所有必需选项的情况，以便你可以预测用户与你的 CLI 交互的各种方式。

如果可能，为选项提供合理的默认值，而不是每次都要求它们。例如，Forge CLI 中的大多数命令都在环境的上下文中运行，我们相信 CLI 的使用将主要发生在应用程序的开发过程中。这就是为什么大多数命令默认在开发环境中运行而不需要提示用户输入此信息的原因。

退出方式简易 #

与大多数 GUI 不同，CLI 没有可见的方法来停止任务运行，除了关闭终端窗口。

为了让用户有一种控制感，你的 CLI 应该有明确标记的退出路径。对于交互式命令，提醒用户有一种简单的方法可以停止任务运行，并且只需很短的 ^C 即可返回到提示符。

标志大于参数 #

正如 Heroku 的 CLI 风格指南所指定的那样，CLI 应该使用标志来标记参数，而不是将参数直接传递到命令中。使用标志意味着用户不需要记住参数顺序，他们只关注要提供的参数。标签还为每个值提供了上下文，提高了可读性。我们建议为常用标志提供简称。

例如，开发人员不会编写像 forge deploy production jira 这样的命令，而是编写 forge deploy --environment production --product jira。有经验的开发者也可以使用简化版：forge deploy -e production -p jira。