Node交互式命令行工具開發(fā)——自動化文檔工具

nodejs開發(fā)命令行工具，流程相對簡單，但一套完整的命令行程序開發(fā)流程下來，還是需要下點功夫，網(wǎng)上資料大多零散，這篇教程意在整合一下完整的開發(fā)流程。

npm上命令行開發(fā)相關(guān)包很多，例如minimist、optimist、nopt、commander.js、yargs等等，使用方法和效果類似。其中用得比較多的是TJ大神的commander和yargs，本文以commander為基礎(chǔ)講述，可以參考這篇教程，yargs教程可以參考阮大神的或者這一篇。

另外，一個完整的命令行工具開發(fā)，還需要了解process、shelljs、path、linebyline等模塊，這些都是node基礎(chǔ)模塊或一些簡單模塊，非常簡單，就不多說了，另外如果你不想用回調(diào)函數(shù)處理異步還需要了解一下Promise、Generator函數(shù)。這是教程：i5ting大神的《深入淺出js（Node.js）異步流程控制》和阮大神的異步編程教程以及promise小人書，另外想嘗試ES7 stage3階段的async/await異步解決方案，可參考這篇教程，async/await解決方案需要babel轉(zhuǎn)碼，這是教程。本人喜歡async/await(哪個node開發(fā)者不喜歡呢？)但不喜歡倒騰，況且async/await本身就是Promise的語法糖，所以沒選擇使用，據(jù)江湖消息，nodejs將在今年晚些時候（10月份？）支持async/await，很是期待。

以下是文章末尾實例用到的一些依賴。

"dependencies": {
    "bluebird": "^3.4.1",
    "co": "^4.6.0",
    "colors": "^1.1.2",
    "commander": "^2.9.0",
    "dox": "^0.9.0",
    "handlebars": "^4.0.5",
    "linebyline": "^1.3.0",
    "mkdirp": "^0.5.1"
  }

其中bluebird用于Promise化，TJ大神的co用于執(zhí)行Generator函數(shù)，handlebars是一種模板，linebyline用于分行讀取文件，colors用于美化輸出，mkdirp用于創(chuàng)建目錄，另外教程中的示例是一款工具，可以自動化生成數(shù)據(jù)庫和API接口的markdown文檔，并通過修改git hooks，使項目的每次commit都會自動更新文檔，借助了TJ大神的dox模塊。

安裝Node

各操作系統(tǒng)下安裝見Nodejs官網(wǎng)，安裝完成之后用node -v或者which node等命令測試安裝是否成功。which在命令行開發(fā)中是一個非常有用的命令，使用which命令確保你的系統(tǒng)中不存在名字相同的命令行工具，例如which commandName，例如which testdev命令返回空白那么說明testdev命令名稱還沒有被使用。

初始化

1. 新建一個.js文件，即是你的命令要執(zhí)行的主程序入口文件，例如testdev.js。在文件第一行加入#!/usr/bin/env node指明系統(tǒng)在運行這個文件的時候使用node作為解釋器，等價于node testdev.js命令。
2. 初始化package.json文件，使用npm init命令根據(jù)提示信息創(chuàng)建，也可以是使用npm init -y使用默認設(shè)置創(chuàng)建。創(chuàng)建完成之后需要修改package.json文件內(nèi)容加入"bin": {"testdev": "./testdev.js"}這條信息用于告訴npm你的命令(testdev)要執(zhí)行的腳本文件的路徑和名字，這里我們指定testdev命令的執(zhí)行文件為當前目錄下的testdev.js文件。
3. 為了方便測試在testdev.js文件中加入代碼console.log('hello world');，這里只是用于測試環(huán)境是否搭建成功，更加復(fù)雜的程序邏輯和過程需要按照實際情況進行編寫

測試

使用npm link命令，可以在本地安裝剛剛創(chuàng)建的包，然后就可以用testdev來運行命令了，如果正常的話在控制臺會打印出hello world

commander

TJ的commander非常簡潔，README.md已經(jīng)把使用方法寫的非常清晰。下面是例子中的代碼：

const program = require('commander'),
  co = require('co');

const appInfo = require('./../package.json'),
  asyncFunc = require('./../common/asyncfunc.js');

program.allowUnknownOption();
program.version(appInfo.version);

program
  .command('init')
  .description('初始化當前目錄doc.json文件')
  .action(() => co(asyncFunc.initAction));

program
  .command('show')
  .description('顯示配置文件狀態(tài)')
  .action(() => co(asyncFunc.showAction));

program
  .command('run')
  .description('啟動程序')
  .action(() => co(asyncFunc.runAction));

program
  .command('modifyhook')
  .description('修改項目下的hook文件')
  .action(() => co(asyncFunc.modifyhookAction));

program
  .command('*')
  .action((env) => {
    console.error('不存在命令 "%s"', env);
  });

program.on('--help', () => {
  console.log('  Examples:');
  console.log('');
  console.log('    $ createDOC --help');
  console.log('    $ createDOC -h');
  console.log('    $ createDOC show');
  console.log('');
});

program.parse(process.argv);

定義了四個命令和個性化幫助說明。

交互式命令行process

commander只是實現(xiàn)了命令行參數(shù)與回復(fù)一對一的固定功能，也就是一個命令必然對應(yīng)一個回復(fù)，那如何實現(xiàn)人機交互式的命令行呢，類似npm init或者eslint --init這樣的與用戶交互，交互之后根據(jù)用戶的不同需求反饋不同的結(jié)果呢。這里就需要node內(nèi)置的process模塊。

這是我實現(xiàn)的一個init命令功能代碼：

exports.initAction = function* () {
  try {
    var docPath = yield exists(process.cwd() + '/doc.json');
    if (docPath) {
      func.initRepl(config.coverInit, arr => {
        co(newDoc(arr));
      })
    } else {
      func.initRepl(config.newInit, arr => {
        co(newDoc(arr));
      })
    }
  } catch (err) {
    console.warn(err);
  }

首先檢查doc.json文件是否存在，如果存在執(zhí)行覆蓋交互，如果不存在執(zhí)行生成交互，try...catch捕獲錯誤。

交互內(nèi)容配置如下：

    newInit:
    [
        {
            title:'initConfirm',
            description:'初始化createDOC,生成doc.json.確認？(y/n)  ',
            defaults: 'y'
        },
        {
            title:'defaultConfirm',
            description:'是否使用默認配置.(y/n)  ',
            defaults: 'y'
        },
        {
            title:'showConfig',
            description:'是否顯示doc.json當前配置？(y/n)  ',
            defaults: 'y'
        }
    ],
    coverInit:[
        {
            title:'modifyConfirm',
            description:'doc.json已存在，初始化將覆蓋文件.確認？(y/n)  ',
            defaults: 'y'
        },
        {
            title:'defaultConfirm',
            description:'是否使用默認配置.(y/n)  ',
            defaults: 'y'
        },
        {
            title:'showConfig',
            description:'是否顯示doc.json當前配置？(y/n)  ',
            defaults: 'y'
        }
    ],

人機交互部分代碼也就是initRepl函數(shù)內(nèi)容如下：

//初始化命令，人機交互控制
exports.initRepl = function (init, func) {
  var i = 1;
  var inputArr = [];
  var len = init.length;
  process.stdout.write(init[0].description);
  process.stdin.resume();
  process.stdin.setEncoding('utf-8');
  process.stdin.on('data', (chunk) => {
    chunk = chunk.replace(/[\s\n]/, '');
    if (chunk !== 'y' && chunk !== 'Y' && chunk !== 'n' && chunk !== 'N') {
      console.log(config.colors.red('您輸入的命令是： ' + chunk));
      console.warn(config.colors.red('請輸入正確指令：y/n'));
      process.exit();
    }
    if (
      (init[i - 1].title === 'modifyConfirm' || init[i - 1].title === 'initConfirm') &&
      (chunk === 'n' || chunk === 'N')
    ) {
      process.exit();
    }
    var inputJson = {
      title: init[i - 1].title,
      value: chunk,
    };
    inputArr.push(inputJson);
    if ((len--) > 1) {
      process.stdout.write(init[i++].description)
    } else {
      process.stdin.pause();
      func(inputArr);
    }
  });
}

人機交互才用向用戶提問根據(jù)用戶不同輸入產(chǎn)生不同結(jié)果的形式進行，順序讀取提問列表并記錄用戶輸入結(jié)果，如果用戶輸入n/N則終止交互，用戶輸入非法字符（除y/Y/n/N以外）提示輸入命令錯誤。

文檔自動化

文檔自動化，其中數(shù)據(jù)庫文檔自動化，才用依賴sequelize的方法手寫（根據(jù)需求不同自行編寫邏輯），API文檔才用TJ的dox也很簡單。由于此處代碼與命令行功能相關(guān)度不大，請讀者自行去示例地址查看代碼。

示例地址

github地址：https://github.com/threerocks/buildDOC

npm地址：https://www.npmjs.com/package/createDOC