Nodejs CLI最佳实践

使用库

启动设计

方括号（[]） 表示可选参数，尖括号（<>） 表示必选参数

总体设计

参考docker命令行设计docker

Usage: docker [OPTIONS] COMAND // 使用方式
A self-sufficient runtime for containers // 描述说明
Options: // 对Options进行描述
  -c, --context string     Name of the context to use to connect to the daemon (overrides DOCKER_HOST env
                           var and default context set with "docker context use")
  -D, --debug              Enable debug mode
// 格式为: 简写/ 命名全称/ 命名描述
Commands: // 名称
  config      Manage Docker configs
  container   Manage containers
  context     Manage contexts
  image       Manage images
// 格式为: 指令/描述
Run 'docker COMMAND --help' for more information on a command.

对子指令进行详细描述

运行命令docker images --help

Usage:  docker images [OPTIONS] [REPOSITORY[:TAG]] // 使用方式
List images // 使用描述
Options: // 可以看出 -a简写的指令，可以识别 --all 和--digests两个复合指令
  -a, --all             Show all images (default hides intermediate images)
      --digests         Show digests
  -f, --filter filter   Filter output based on conditions provided
      --format string   Pretty-print images using a Go template
      --no-trunc        Don't truncate output
  -q, --quiet           Only show image IDs

CLI状态存储和描述

指令	状态存储工具	config(配置文件)存储
docker	~/.docker	~/.docker
gatsby-cli	configstore	~/.config/gatsby
firebase-tools	configstore	~/.config/configstore

文件读写XDG基本的目录规范

基本概念

• XDG_DATA_HOME 下存放用户数据文件，默认值是 ~/.local/share
• XDG_CONFIG_HOME 下存放用户配置文件，默认值是 ~/.config
• XDG_DATA_DIRS 定义一组以 : 分隔的有序目录集，规定了除 XDG_DATA_HOME 外的搜索路径，默认值是 /usr/local/share/:/usr/share/
• XDG_CONFIG_DIRS 定义一组以 : 分隔的有序目录集，规定了除 XDG_CONFIG_HOME 外的搜索路径，默认值是 /etc/xdg
• XDG_CACHE_HOME 下存放用户的缓存文件，默认值是 ~/.cache
• XDG_RUNTIME_DIR 下存放运行时的用户文件，比如 sockets、named pipes。此目录必须属于该用户，并且他必须是用户中唯一拥有读/写操作的以为，换句话说便是 0700 权限

体验设计

提供有色彩的体验

推荐使用 chalk或者 colors 等NPM包来使用颜色来突出显示应用程序输出的一部分

丰富的交互行为

• Inquirer/enquirer/prompts等，用于丰富可交互的API，包括对话提示，表单填写，选择等行为。star数Inquirer > prompts > enquirer
• ora 在终端界面进行loading 的效果
• ink 使用React组件的方式来编写CLI命令(非常有创意)

无处不在的超链接

加上正确的超链接的格式比如http或者https 同时通过显示的标识代表是超链接样式chalk.underline('https://opencollective.com/nest')

错误设计

信息性错误

返回错误消息的时候，确保他们包含参考号或者特定错误代码，以便以后查阅，和HTTP状态错误码非常相似

$ my-cli-tool --doSomething

Error (E4002): please provide an API token via environment variables

提供调试模式

使用环境变量或者命令行参数设置调试并打开扩展的详细信息，在代码有意义的地方设置调试信息，帮助用户和维护人员了解程序流、输入和输出以及其他使问题解决更容易的信息。
推荐使用包

• debug

开发

使用bin对象

使用一个对象来定义可执行文件的名称和路径

1. nest-cli
   package.json

"bin": {
    "nest": "bin/nest.js"
  },

bin/nest.js

#!/usr/bin/env node
"use strict";
const commander = require("commander");

2. netlify-cli

package.json

"bin": {
    "ntl": "bin/run",
    "netlify": "bin/run"
  },

bin/run

#!/usr/bin/env node
require('..').run()
.catch(require('@oclif/errors/handle'))

使用相对路径

使用process.cwd() 访问用户输入路径，使用__dirname访问基于项目的路径

使用files字段

files是一个数组, 它描述了你 npm publish的时候推送到npm服务器的文件列表,支持目录和通配 比如

"files": [
  "src",
  "!src/**/*.spec.js"
],