命令行界面指南

# 命令行界面指南 来源：https://clig.dev/ 一份开源 (https://github.com/cli-guidelines/cli-guidelines) 指南，旨在帮助你编写更好的命令行程序，它借鉴了传统 UNIX 原则，并针对现代环境进行了更新。 **Aanand Prasad** Squarespace 工程师，Docker Compose 联合创始人。 @aanandprasad (https://twitter.com/aanandprasad) **Ben Firshman** Replicate (https://replicate.com/) 联合创始人，Docker Compose 联合创始人。 @bfirsh (https://twitter.com/bfirsh) **Carl Tashian** Smallstep (https://smallstep.com/) 离岸工程师，Zipcar 首位工程师，Trove 联合创始人。 tashian.com (https://tashian.com/) @tashian (https://twitter.com/tashian) **Eva Parish** Squarespace 技术作家，O'Reilly 贡献者。 evaparish.com (https://evaparish.com/) @evpari (https://twitter.com/evpari) 设计由 Mark Hurrell (https://mhurrell.co.uk/) 完成。感谢 Andreas Jansson 的早期贡献，以及 Andrew Reitz、Ashley Williams、Brendan Falk、Chester Ramey、Dj Walker-Morgan、Jacob Maine、James Coglan、Michael Dwan 和 Steve Klabnik 对草稿的审阅。 如果你想讨论本指南或 CLI 设计，请加入我们的 Discord (https://discord.gg/EbAW5rUCkE)。 ## 前言 在 20 世纪 80 年代，如果你想让个人电脑为你做点什么，你就需要在面对 `C:\>` 或 `~$` 时知道该输入什么。 帮助来自厚厚的螺旋装订手册。错误信息晦涩难懂。没有 Stack Overflow 来拯救你。 但如果你足够幸运能接入互联网，你可以从 Usenet 获得帮助——这是一个早期的互联网社区，里面充满了和你一样沮丧的人。他们要么帮你解决问题，要么至少提供一些精神支持和友谊。 四十年后，计算机对每个人来说都变得更容易访问了，但这往往是以牺牲底层终端用户控制为代价的。在许多设备上，根本没有命令行访问权限，部分原因是这违背了围墙花园和应用商店的企业利益。如今大多数人不知道命令行是什么，更不用说为什么他们要费心去使用它了。 正如计算先驱 Alan Kay 在 2017 年的一次采访 (https://www.fastcompany.com/40435064/what-alan-kay-thinks-about-the-iphone-and-technology-now) 中所说：“因为人们不了解计算是什么，他们以为在 iPhone 上就拥有了它，这种错觉和认为‘吉他英雄’等同于真正的吉他一样糟糕。” Kay 所说的“真正的吉他”并非特指 CLI——不完全是。他谈论的是编程计算机的方式，这些方式提供了 CLI 的能力，并且超越了在文本文件中编写软件的范畴。Kay 的追随者中有人认为，我们需要突破几十年来一直所处的基于文本的局部最优。想象一个我们以截然不同的方式编程计算机的未来，令人兴奋。 即使在今天，电子表格仍然是最流行的编程语言，无代码运动也正在迅速兴起，试图取代对才华横溢的程序员的巨大需求。然而，尽管有陈旧、几十年的限制和难以解释的怪癖，命令行仍然是计算机中 *最多功能* 的角落。它让你拉开帷幕，看看真正发生了什么，并以 GUI 无法企及的复杂性和深度与机器进行创造性交互。它在几乎所有笔记本电脑上都可以使用，供任何想学习的人使用。它可以交互式使用，也可以自动化。而且，它不像系统的其他部分那样变化迅速。它的稳定性具有创造价值。 所以，当我们还拥有它时，我们应该努力最大化它的效用和可访问性。 自从早期以来，我们编程计算机的方式已经发生了很多变化。过去的命令行是 *以机器为先*：基本上就是一个脚本平台上的 REPL。但随着通用解释型语言的蓬勃发展，shell 脚本的角色已经缩小了。今天的命令行是 *以人为本*：一个基于文本的 UI，允许访问各种工具、系统和平台。过去，编辑器在终端内部——今天，终端往往只是编辑器的一个功能。 而且出现了大量类似 `git` 的多工具命令。命令嵌套命令，以及执行整个工作流程而不是原子功能的高级命令。 受传统 UNIX 哲学的启发，出于鼓励更愉悦、更易访问的 CLI 环境的兴趣，并以我们作为程序员的经验为指导，我们认为现在是重新审视构建命令行程序的最佳实践和设计原则的时候了。 命令行万岁！ ## 引言 本文档涵盖了高层次的设计哲学和具体的指南。指南部分更多，因为我们作为实践者的哲学是不进行过多的哲学思考。我们相信通过例子学习，所以我们提供了大量例子。 本指南不涵盖像 emacs 和 vim 这样的全屏终端程序。全屏程序是小众项目——我们中很少有人会有机会设计一个。 本指南也对编程语言和工具保持不可知。 本指南是为谁准备的？ - 如果你正在创建一个 CLI 程序，并且正在寻找其 UI 设计的原则和具体最佳实践，那么本指南适合你。 - 如果你是一名专业的“CLI UI 设计师”，那太棒了——我们很乐意向你学习。 - 如果你想避免那些违背 40 年 CLI 设计惯例的明显错误，那么本指南适合你。 - 如果你想通过良好的设计和有帮助的帮助信息让用户感到愉悦，那么本指南绝对适合你。 - 如果你正在创建 GUI 程序，那么本指南不适合你——尽管如果你决定阅读，可能会学到一些 GUI 的反模式。 - 如果你正在为 Minecraft 设计一个沉浸式的全屏 CLI 移植版，那么本指南不适合你。（但我们迫不及待地想看到它！） ## 哲学 以下是我们认为的良好 CLI 设计的基本原则。 ### 以人为本的设计 传统上，UNIX 命令的编写假设它们主要被其他程序使用。它们与编程语言中的函数有更多共同点，而不是与图形应用程序。 如今，尽管许多 CLI 程序主要（甚至完全）由人类使用，但它们的交互设计中很多仍然带有过去的包袱。是时候摆脱一些包袱了：如果一个命令主要用于人类，那么它应该首先为人类设计。 ### 协同工作的简单部件 原始 UNIX 哲学 (https://en.wikipedia.org/wiki/Unix_philosophy) 的一个核心原则是，小而简单的程序具有清晰的接口，可以组合起来构建更大的系统。与其在这些程序中塞入越来越多的功能，不如让它们足够模块化，以便根据需要重新组合。 在过去，管道和 shell 脚本在组合程序的过程中发挥了关键作用。随着通用解释型语言的兴起，它们的作用可能有所减弱，但肯定没有消失。 更重要的是，大规模自动化——以 CI/CD、编排和配置管理的形式——蓬勃发展。让程序可组合与以往一样重要。 幸运的是，UNIX 环境中长期建立的约定正是为此目的而设计的，至今仍在帮助我们。标准输入/输出/错误、信号、退出码和其他机制确保不同的程序能很好地协同工作。简单的、基于行的文本易于在命令之间管道传递。JSON，一个更新得多的发明，在我们需要时提供了更多的结构，并让我们更容易地将命令行工具与 Web 集成。 无论你在构建什么软件，你都可以完全确定人们会以你没有预料到的方式使用它。你的软件 *将* 成为更大系统的一部分——你唯一的选择是它将成为一个行为良好的部分还是不好的部分。 最重要的是，为可组合性进行设计不必与以人为本的设计相冲突。本文档中的许多建议都是关于如何实现这两者。 ### 跨程序的一致性 终端的约定已经深深刻在我们的手指里。我们必须通过了解命令行语法、标志、环境变量等支付前期成本，但只要程序保持一致，它就能在长期效率上获得回报…… 在可能的情况下，CLI 应该遵循已有的模式。这使得 CLI 直观且可猜测；这使得用户高效。 话虽如此，有时一致性与易用性冲突。例如，许多长期建立的 UNIX 命令默认不输出太多信息，这可能会让不太熟悉命令行的人感到困惑或担忧。当遵循约定会损害程序的可用性时，可能是时候打破常规了——但这样的决定应该谨慎做出。 ### 说（恰到好处的）话 终端是一个纯粹信息的世界。你可以说信息就是界面——就像任何界面一样，信息往往太多或太少。 当一个命令挂起几分钟，用户开始怀疑它是否坏了时，它说得太少了。当一个命令倾倒几页的调试输出，将真正重要的内容淹没在大量松散碎屑的海洋中时，它说得太多了。 最终结果是相同的：缺乏清晰度，让用户感到困惑和恼火。很难把握好这个平衡，但如果软件要赋能和服务其用户，这绝对至关重要。 ### 易于发现 在使功能可发现方面，GUI 具有优势。你能做的所有事情都摆在屏幕上，所以你可以无需了解任何东西就能找到你需要的，甚至可能发现你不知道可能的事情。 人们认为命令行界面与此相反——你必须记住如何做每件事。 1987 年发布的原始 Macintosh 人机界面指南 (https://archive.org/details/applehumaninterf00appl) 建议“看到并指向（而不是记住并输入）”，仿佛你只能选择其中之一。 这些不一定互斥。使用命令行的效率来自于记住命令，但没有理由命令不能帮助你学习和记忆。 可发现的 CLI 具有全面的帮助文本，提供大量示例，建议接下来运行什么命令，以及在出现错误时建议该做什么。有很多可以从 GUI 借鉴的想法，使 CLI 更容易学习和使用，即使对于高级用户也是如此。 *引用：《设计心理学》（唐·诺曼），Macintosh 人机界面指南* ### 对话作为常态 GUI 设计，特别是在早期，大量使用了 *隐喻*：桌面、文件、文件夹、回收站。这很有道理，因为计算机仍在努力为自己争取合法性。隐喻易于实现是 GUI 相对于 CLI 的巨大优势之一。 然而具有讽刺意味的是，CLI 一直体现着一个偶然的隐喻：它是一场对话。 除了最简单的命令之外，运行一个程序通常涉及不止一次调用。通常，这是因为第一次很难做对：用户输入一个命令，得到一个错误，更改命令，得到另一个错误，等等，直到成功。这种通过反复失败来学习的方式就像用户与程序之间的对话。 然而，试错并非唯一的对话式交互类型。还有其他的： - 运行一个命令来设置一个工具，然后学习要运行什么命令来真正开始使用它。 - 运行几个命令来设置一个操作，然后运行最终命令来执行它（例如，多次 `git add`，然后执行 `git commit`）。 - 探索一个系统——例如，做很多 `cd` 和 `ls` 来了解目录结构，或者 `git log` 和 `git show` 来探索文件的历史。 - 在真正运行复杂操作之前进行试运行。 承认命令行交互的对话性质意味着你可以将相关技术应用到其设计中。你可以建议在用户输入无效时可能进行的纠正，你可以让中间状态清晰明了，当用户经历多步骤过程时，你可以确认一切看起来没问题，然后他们才做可怕的事情。 无论你是否有意，用户都在与你的软件对话。最坏的情况下，这是一场充满敌意的对话，让他们感到愚蠢和怨恨。最好的情况下，这是一场愉快的交流，让他们带着新发现的知识和成就感快速前进。 *延伸阅读：《反 Mac 用户界面》（Don Gentner 和 Jakob Nielsen）(https://www.nngroup.com/articles/anti-mac-interface/)* ### 健壮性 健壮性既是客观属性也是主观属性。软件当然应该 *是* 健壮的：意外输入应该被优雅地处理，操作应该在可能的情况下是幂等的，等等。但它也应该 *感觉* 健壮。你想让你的软件感觉它不会散架。你想让它感觉即时和响应迅速，就像一台大的机械机器，而不是一个脆弱的塑料“软开关”。 主观的健壮性需要关注细节，并深入思考可能出错的地方。这是许多小事情：让用户了解正在发生的事情，解释常见错误意味着什么，不要打印看起来很吓人的堆栈跟踪。 作为一般规则，健壮性也可以来自保持简单。大量的特殊情况和高复杂的代码往往会使程序变得脆弱。 ### 同理心 命令行工具是程序员的创造性工具箱，所以它们应该让人喜欢使用。这并不意味着把它们变成电子游戏，或者使用很多表情符号（尽管表情符号本身没有什么问题😉）。这意味着让用户感觉到你站在他们一边，你希望他们成功，你仔细考虑过他们的问题以及如何解决。 没有一份你可以采取的行动清单能确保他们有这样的感受，尽管我们希望遵循我们的建议能让你在某种程度上达到目标。取悦用户意味着在每一个环节 *超越他们的期望*，而这始于同理心。 ### 混乱 终端世界是一团糟。不一致之处随处可见，让我们慢下来，让我们自我怀疑。然而无可否认，这种混乱一直是力量的源泉。终端，就像整个 UNIX 派生的计算环境一样，对你所能构建的东西几乎没有限制。在这个空间里，各种各样的创造百花齐放。 讽刺的是，本文档恳求你遵循现有模式，同时又提出了与几十年命令行传统相悖的建议。我们和其他人一样，也违反规则。可能有一天你也必须打破规则。那么，要有意图和明确的目标去这样做。 > “当标准明显损害生产力或用户满意度时，就放弃它。”——杰夫·拉斯金，《人本界面》 (https://en.wikipedia.org/wiki/The_Humane_Interface) ## 指南 这是一系列你可以采取的具体措施，以改进你的命令行程序。 第一部分包含了你需要遵循的基本要点。如果这些方面做错了，你的程序要么难以使用，要么会成为糟糕的 CLI 公民。其余部分则是锦上添花。如果你有时间和精力来添加这些……