如何为开源项目设计CLI工具？

本文目录导读：

1. 第一阶段：明确核心原则
2. 第二阶段：逻辑架构设计
3. 第三阶段：具体设计要素
4. 第四阶段：代码实现与库选择
5. 第五阶段：发布与文档（关键冷启动步骤）
6. 总结清单：设计检查表

为开源项目设计CLI工具，核心在于遵循 Unix哲学（做一件事，做好它）并兼顾 用户体验（易发现、易记忆、易纠错），以下是一套从零开始的系统设计流程，包含了原则、结构和实操建议。

第一阶段：明确核心原则

在设计每一个标志（flag）和命令（command）之前,先建立以下三个信条：

1. 可发现性 (Discoverability)：用户不需要查看文档就能基本猜出怎么用。--help 必须详尽、美观、高信息密度。
2. 一致性 (Consistency)：遵循业界约定俗成的“方言”，比如用 -v 表示 verbose（详细输出）或 version（版本），而不是用 -V 表示 volume（音量）。
3. 可组合性 (Composability)：输入和输出应该是纯文本（如 JSON、CSV 或简单的表格），方便通过管道（ ）与其他命令（ grep, jq, awk ）协作。

第二阶段：逻辑架构设计

CLI 工具的设计模式主要有两种,选择哪一种取决于你工具的功能复杂度：

• 模式 A：单一命令模式 (Git Style) —— 适用于功能单一的工具。

  • 示例：curl, grep, jq。
  • 设计：只有一个动词，通过 -o（输出到文件）、-i（忽略大小写）等 flag 调整行为。
  • 适合场景：格式化、转换、简单的文件操作。

• 模式 B：多命令 / 子命令模式 (Docker / Kubernetes Style) —— 适用于平台级或功能复杂的工具。

  • 示例：docker run, docker ps, kubectl get pods。
  • 设计：顶层命令 + 子命令，通常包含 create, delete, list, describe, apply。
  • 适合场景：管理API资源、工作流编排、项目脚手架。

决策建议：如果工具需要管理超过3种不同的实体或动作，直接采用模式B,因为后期扩展时重构CLI结构是非常痛苦的。

第三阶段：具体设计要素

命名规范 (Naming)

• 大写的标志：一般保留给 Go 或 OS 环境变量，CLI 中标志使用小写和连字符 （ --output-format ）。
• 短标志：只给最常用的功能。-h 保留给帮助，-v 保留给版本或详细输出。
• 双短划线：长标志用 ，短标志用 。

命令与参数结构 (Structure)

• 命令结构：<tool> <verb> <noun> <flags>
  • 好例子：mycloud server create --name web-1 --flavor small
  • 坏例子：mycloud --create-server web-1 small
• 位置参数 vs. 命名参数：
  • 用户最容易理解的是 命名参数（通过 --name 指定），位置参数只应用于列表、文件路径等 显而易见 且 唯一 的对象。git commit <path> 或 rm <file>。

标志设计守则 (Flags)

交互与反馈 (Interaction)

• 进度条：如果任务超过500ms，显示 spinner（旋转器）或进度条。
• 颜色：使用颜色区分信息（蓝色/绿色）、警告（黄色）、错误（红色），但必须支持 --no-color 或通过 NO_COLOR 环境变量关闭。
• 错误消息：错误消息必须包含 三要素：发生了什么错误、为什么发生、如何解决。

  Error: Could not connect to server at 192.168.1.1:8080
  Reason: Timeout after 10 seconds.
  Fix: Check your network and ensure the server is running. Try --server <address> to specify a different endpoint.

第四阶段：代码实现与库选择

选择合适的编程语言和库能极大降低维护成本。

• 语言选择：Go（编译为单二进制，分发简单）、Rust（速度快、安全性好）、Python（生态丰富，但依赖管理麻烦）。
• 推荐库：
  • Go：cobra（事实标准，用于 kubectl、hugo） + viper（管理配置）,Cobra会自动生成帮助文档和自动补全。
  • Python：click（API优雅，支持嵌套命令） 或 Typer（基于click，但使用类型提示，代码更少）。
  • Rust：clap（功能强大，自动生成手册）。
  • Node.js：commander.js（轻量） 或 yargs（功能全面）。

第五阶段：发布与文档（关键冷启动步骤）

很多优秀的CLI工具因为文档难懂而被埋没。

1. 自动生成帮助：确保 --help 输出排版整齐。

   Usage: mytool [command] [options]
   A command-line tool for managing cloud instances
   Commands:
     create   Create a new instance
     list     List all instances
     delete   Remove an instance
   Flags:
     -h, --help      Show help
     -v, --version   Show version

2. Man Page（手册页）或 Markdown 文档：为你的项目提供 mycommand docs 命令或在线文档，最好的文档是 一个 README.md 文件,里面包含一个从安装到完成任务的完整例子。

   • 坏例子：列出100个flag的列表。

   • 好例子：

     # 安装
     brew install mycli
     # 创建一个名为 "my-prod-app" 的服务器
     mycli server create --name prod-1 --env production
     # 查看状态
     mycli server status prod-1

3. Shell 自动补全：必须支持！提供 completion 子命令 (如 mycli completion bash)，用户只需 source <(mycli completion bash) 即可。

总结清单：设计检查表

1. [ ] 遵循 POSIX 标准：短标志可组合（如 -abc 等于 -a -b -c）。
2. [ ] 支持 --help 和 --version。
3. [ ] 支持 --color / --no-color。
4. [ ] 支持环境变量 (如 MYCLI_SERVER_ADDR) 覆盖 flag 默认值。
5. [ ] 支持配置文件 (如 .myclirc 或 mycli config set ...)。
6. [ ] 输出结构化数据 (JSON) 作为机器可读的默认输出,同时提供美化表格供人阅读。
7. [ ] 提供 Shell 自动补全（bash, zsh, fish）。
8. [ ] 错误消息包含Fix建议（不要只说“Something went wrong”）。

最后一步：实际测试 将你的CLI交给没有看过文档的用户，让他们完成一个简单的任务（创建一个文件并列出内容”），观察他们卡在哪里，如果一个用户需要翻看帮助超过2次才能完成最基本的流程,你的CLI设计就需要简化了。