真香！原來 CLI 開發可以這麼簡單

CLI（命令列工具，Command Line Interface）大家都非常熟悉了，比如 create-react-app 等。我們今天介紹一個 CLI 工具的開發框架，可以幫助我們快速構建 CLI 工具。

oclif（發音為 'oh-cliff'）是一個命令列工具開發框架，功能豐富，開發方便。同時 oclif 還支援通過 TypeScript 來開發，對於習慣使用 TypeScript 的同學來說非常友好。

基本用法

oclif 提供兩種執行模式，一種是單一命令模式，類似於 curl，通過各種引數使用不同的功能。另一種是多命令模式，類似於 git，可以定義子命令來實現不同的功能。

下面的兩個樣例分別展示了單一命令模式和多命令模式的使用方法.

$ npx oclif single mynewcli

? npm package name (mynewcli): mynewcli

$ cd mynewcli

$ ./bin/run

hello world from ./src/index.js!

單命令模式下，會在 src 目錄下生成一個 index.{ts,js} 檔案，我們在這個檔案裡定義命令。

$ npx oclif multi mynewcli

? npm package name (mynewcli): mynewcli

$ cd mynewcli

$ ./bin/run --version

mynewcli/0.0.0 darwin-x64 node-v9.5.0

$ ./bin/run --help

USAGE

  $ mynewcli [COMMAND]

COMMANDS

  hello

  help   display help for mynewcli

$ ./bin/run hello

hello world from ./src/hello.js!

多命令模式下，會在 src 目錄下生成一個 commands 目錄，這個目錄下的每一個檔案就是一個子命令。比如 ./src/commands/hello.ts、./src/commands/goodbye.ts。

注意，多命令模式下命令和檔案之間一個隱式的對應關係，比如 src/commands 目錄下的檔案是子命令。如果 src/commands 下是一個目錄，則目錄下的多個檔案會形成一個 Topic。

加入有如下目錄結構：

package.json

src/

└── commands/

    └── config/

        ├── index.ts

        ├── set.ts

        └── get.ts

那麼，命令最終的執行形式為： mynewcli config，mynewcli config:set 和 mynewcli config:get。

定義命令

不管是單一命令模式還是多命令模式，開發者只需要定義一個 class 繼承 Command 類即可。

import Command from '@oclif/command'

export class MyCommand extends Command {

  static description = 'description of this example command'

  async run() {

    console.log('running my command')

  }

}

如上，在命令執行地時候，會自動執行 run 方法。

Command 還提供了很多工具方法，比如 this.log、this.warn、this.error、this.exit 等，方便在執行過程中列印日誌資訊。

命令列工具通常都需要定義一些引數，oclif 支援兩種引數定義形式，一種是 argument，用於定義有順序要求的引數，一種是 flag，用於定義沒有順序要求的引數。

定義 argument

argument 的使用如下：

$ mycli firstArg secondArg # 引數順序不能亂

我們可以這樣定義 argument 引數：

import Command from '@oclif/command'

export class MyCLI extends Command {

  static args = [

    {name: 'firstArg'},

    {name: 'secondArg'},

  ]

  async run() {

    // 通過物件的形式獲取引數

    const { args } = this.parse(MyCLI)

    console.log(`running my command with args: ${args.firstArg}, ${args.secondArg}`)

    // 也可以通過陣列的形式獲取引數

    const { argv } = this.parse(MyCLI)

    console.log(`running my command with args: ${argv[0]}, ${argv[1]}`)

  }

}

我們可以對 argument 引數進行屬性定義：

static args = [

  {

    name: 'file',               // 引數名稱，之後通過 argv[name] 的形式獲取引數

    required: false,            // 是否必填

    description: 'output file', // 引數描述

    hidden: true,               // 是否從命令的 help 資訊中隱藏

    parse: input => 'output',   // 引數處理函式，可以改變使用者輸入的值

    default: 'world',           // 引數預設值

    options: ['a', 'b'],        // 引數的可選範圍

  }

]

定義 flag

flag 的使用形式如下：

$ mycli --force --file=./myfile

我們可以這樣定義 flag 引數：

import Command, {flags} from '@oclif/command'

export class MyCLI extends Command {

  static flags = {

    // 可以通過 --force 或 -f 來指定引數

    force: flags.boolean({char: 'f'}),

    file: flags.string(),

  }

  async run() {

    const {flags} = this.parse(MyCLI)

    if (flags.force) console.log('--force is set')

    if (flags.file) console.log(`--file is: ${flags.file}`)

  }

}

我們可以對 flag 引數進行屬性定義：

static flags = {

  name: flags.string({

    char: 'n',                    // 引數短名稱

    description: 'name to print', // 引數描述

    hidden: false,                // 是否從 help 資訊中隱藏

    multiple: false,              // 是否支援對這個引數設定多個值

    env: 'MY_NAME',               // 預設值使用的環境變數的名稱

    options: ['a', 'b'],          // 可選值列表

    parse: input => 'output',     // 對使用者輸入進行處理

    default: 'world',             // 預設值，也可以是一個返回字串的函式

    required: false,              // 是否必填

    dependsOn: ['extra-flag'],    // 依賴的其他 flag 引數列表

    exclusive: ['extra-flag'],    // 不能一起使用的其他 flag 引數列表

  }),

  // 布林值引數

  force: flags.boolean({

    char: 'f',

    default: true,                // 預設值，可以是一個返回布林值的函式

  }),

}

使用生命週期鉤子

oclif 提供了一些生命週期鉤子，可以讓開發者在工具執行的各個階段進行一些額外操作。

我們可以這樣定義一個鉤子函式：

import { Hook } from '@oclif/config'

export default const hook: Hook<'init'> = async function (options) {

  console.log(`example init hook running before ${options.id}`)

}

同時，還需要在 package.json 中註冊這個鉤子函式：

"oclif": {

  "commands": "./lib/commands",

  "hooks": {

    "init": "./lib/hooks/init/example"

  }

}

oclif 還支援定義多個鉤子函式，多個鉤子函式會並行執行：

"oclif": {

  "commands": "./lib/commands",

  "hooks": {

    "init": [

      "./lib/hooks/init/example",

      "./lib/hooks/init/another_hook"

    ]

  }

}

目前支援的生命週期鉤子如下：

init - 在 CLI 完成初始化之後，找到對應命令之前。
prerun - 在 init 完成，並找到對應命令之後，但是在命令執行之前。
postrun - 在命令執行結束之後，並沒有錯誤發生。
command_not_found - 沒有找到對應命令，在展示錯誤資訊之前。

使用外掛

oclif 官方和社群提供了很多有用的外掛可以供新開發的命令列工具使用，只需要在 package.json 中宣告即可。

{

  "name": "mycli",

  "version": "0.0.0",

  // ...

  "oclif": {

    "plugins": [

      "@oclif/plugin-help",

      "@oclif/plugin-not-found"

    ]

  }

}

可用的外掛有：

@oclif/plugin-not-found 當未找到命令的時候提供一個友好的 "did you mean" 資訊。
@oclif/plugin-plugins 允許使用者給你的命令列工具新增外掛。
@oclif/plugin-update 自動更新外掛。
@oclif/plugin-help 幫助資訊外掛。
@oclif/plugin-warn-if-update-available 當有可用更新時，展示一個警告資訊提示更新。
@oclif/plugin-autocomplete 提供 bash/zsh 的自動補全。

錯誤處理

命令列執行難免會出錯，oclif 提供了兩種錯誤處理的方法。

`Command.catch`

每個 Command 例項都有一個 catch 方法，開發者可以在這個方法中處理錯誤。

import {Command, flags} from '@oclif/command'

export default class Hello extends Command {

  async catch(error) {

    // do something or

    // re-throw to be handled globally

    throw error;

  }

}

`bin/run` 的 `catch`

bin/run 是每個 oclif 命令列工具的入口檔案，我們可以通過 bin/run 的 catch 方法抓取錯誤，包括 Command 中重新丟擲的錯誤。

.catch(require('@oclif/errors/handle'))

//或

.catch((error) => {

  const oclifHandler = require('@oclif/errors/handle');

  // do any extra work with error

  return oclifHandler(error);

})

其他功能

cli-ux

oclif 官方維護的 cli-ux 庫提供了許多使用的功能。

通過 cliux.prompt() 函式可以實現簡單的互動功能。如果有更復雜的互動需求，可以使用 inquirer。
通過 cliux.action 可以實現旋轉 loading 效果。
通過 cliux.table 可以展示表格資料。

node-notifier

通過 node-notifier 可以實現跨平臺的通知資訊展示。

常見面試知識點、技術解決方案、教程，都可以掃碼關注公眾號“眾裡千尋”獲取，或者來這裡 https://everfind.github.io 。

真香！原來 CLI 開發可以這麼簡單