在項(xiàng)目建立初期引入一些最佳實(shí)踐可以避免后期大量復(fù)雜的重構(gòu)工作，本文總結(jié)了在使用Node JS構(gòu)建Web服務(wù)時(shí)的一些最佳實(shí)踐，同時(shí)涉及的具體的操作步驟。

一、使用初始化腳手架

所謂腳手架，就是在初始化代碼庫(kù)時(shí)，腳手架可以幫助自動(dòng)生成一些代碼和項(xiàng)目結(jié)構(gòu)，注入一些框架。對(duì)于一個(gè)NodeJS項(xiàng)目，不需要我們從npm init初始化起，自己一步步安裝一些依賴。

Express命令

Express是目前最流行的NodeJS web框架。全局安裝一個(gè)express-generator，用來(lái)初始化express項(xiàng)目。

• 全局安裝命令：npm install express-generator -g

• 新建一個(gè)名為hello-express項(xiàng)目: express hello-express
  

  使用腳手架初始化Express項(xiàng)目

使用Swagger腳手架

當(dāng)使用NodeJS 開發(fā)Web API時(shí)，強(qiáng)烈建議使用Swagger進(jìn)行API構(gòu)建與管理，以及提供API文檔服務(wù)。全局安裝swagger命令也可以實(shí)現(xiàn)初始化一個(gè)swagger項(xiàng)目。swagger命令可以讓你在瀏覽器上實(shí)時(shí)直接編輯你的API定義和調(diào)試API。

初始化swagger項(xiàng)目

• 安裝命令：npm install swagger -g
• 新建Swagger API項(xiàng)目：swagger project create hello-swagger，在這過(guò)程中會(huì)讓你選擇使用哪種Web服務(wù)器，當(dāng)選擇express時(shí)就可以自動(dòng)引入express框架
• 項(xiàng)目結(jié)構(gòu)：

.
├── README.md
├── api
│   ├── controllers
│   │   ├── README.md
│   │   └── hello_world.js
│   ├── helpers
│   │   └── README.md
│   ├── mocks
│   │   └── README.md
│   └── swagger
│       └── swagger.yaml
├── app.js
├── config
│   ├── README.md
│   └── default.yaml
├── package-lock.json
├── package.json
└── test
    └── api
        ├── controllers
        │   ├── README.md
        │   └── hello_world.js
        └── helpers
            └── README.md

實(shí)時(shí)編輯和語(yǔ)法校驗(yàn)

• 啟動(dòng)在線編輯：swagger project edit, 此時(shí)會(huì)打開系統(tǒng)瀏覽器，在瀏覽器中可以直接編輯swagger文檔，并進(jìn)行實(shí)時(shí)語(yǔ)法檢查，同時(shí)瀏覽器里面的編輯變更會(huì)回寫到代碼。

Swagger實(shí)時(shí)編輯和語(yǔ)法校驗(yàn)

在線調(diào)試API

上圖右側(cè)部分，就是類似于 postman的API調(diào)試工具。

二、Swagger文檔服務(wù)

Swagger是一個(gè)最流行的的API構(gòu)建與管理工具，在各種語(yǔ)言和框架都有相應(yīng)的庫(kù)可以支持，同時(shí)安裝swagger-ui擴(kuò)展進(jìn)行API文檔管理和在線調(diào)試。
其遵循OpenAPI標(biāo)準(zhǔn)，OpenAPI定義了諸如路由轉(zhuǎn)發(fā)、參數(shù)定義與校驗(yàn)等一整套API規(guī)范。

• OpenAPI規(guī)范文檔：https://swagger.io/specification/
• 在線API編輯器預(yù)覽：https://editor.swagger.io

發(fā)布swagger文檔

上面的swagger命令適合在本地編輯、調(diào)試使用，當(dāng)在產(chǎn)品（Production）環(huán)境發(fā)布文檔服務(wù)時(shí)，適合引入 swagger UI 中間件

app.use(SwaggerUi(swaggerExpress.runner.swagger));

訪問(wèn)http://localhost:10010/docs/#/即可查看API文檔：

Swagger UI

• 在線預(yù)覽：https://petstore.swagger.io/

• 完整代碼如下：

SwaggerExpress.create(config, function (err, swaggerExpress) {
  if (err) {
    throw err;
  }

  // install middleware
  app.use(SwaggerUi(swaggerExpress.runner.swagger));
  swaggerExpress.register(app);

  const port = 10010;
  app.listen(port);

  if (swaggerExpress.runner.swagger.paths['/hello']) {
    console.log('try this:\ncurl http://127.0.0.1:' + port + '/hello?name=Scott');
  }
});

三、啟用ES6 JS語(yǔ)法

ECMAScript 是 JS 的語(yǔ)言標(biāo)準(zhǔn)，ES6是新的JS語(yǔ)法標(biāo)準(zhǔn)。在沒(méi)有其它配置的情況下使用ES6語(yǔ)法會(huì)出現(xiàn)一下錯(cuò)誤。我們需要引入babel做語(yǔ)法轉(zhuǎn)換。

import SwaggerExpress from 'swagger-express-mw';
       ^^^^^^^^^^^^^^

SyntaxError: Unexpected identifier
    at Module._compile (internal/modules/cjs/loader.js:760:23)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:827:10)

什么是babel

Babel 是一個(gè) JavaScript 編譯器，工具鏈，主要用于將 ECMAScript 2015+ 版本的代碼轉(zhuǎn)換為向后兼容的 JavaScript 語(yǔ)法，以便能夠運(yùn)行在當(dāng)前和舊版本的瀏覽器或其他環(huán)境中。更多文檔可參考：https://www.babeljs.cn/docs/

如何配置？

• 安裝依賴：

npm install -D @babel/core @babel/cli @babel/preset-env @babel/node

• 在根目錄創(chuàng)建.babelrc文件，內(nèi)容如下

{ 
  "presets": ["@babel/preset-env"] 
}

• 使用babel-node命令代替node

"scripts": {
    "start": "npm run prod",
    "server": "node ./app.js"  // -> "babel-node ./app.js"
}

如何處理已有的非ES6項(xiàng)目？

安裝一個(gè)npm module cjs-to-es6 可以做一些簡(jiǎn)單的ES6語(yǔ)法轉(zhuǎn)化：

npm install -g cjs-to-es6

參考資料

• https://www.babeljs.cn/docs/
• How to enable ES6 (and beyond) syntax with Node and Express：https://medium.freecodecamp.org/how-to-enable-es6-and-beyond-syntax-with-node-and-express-68d3e11fe1ab

四、文件變動(dòng)監(jiān)聽并自動(dòng)重啟服務(wù)

每次修改代碼時(shí)我們需要重啟Express來(lái)查看效果，nodemon可以在指定的文件發(fā)生修改后，幫助我們自動(dòng)重啟服務(wù)，提高開發(fā)效率。

• 安裝nodemon：npm i -D nodemon
• 在根目錄添加配置文件nodemon.json：

{
  "exec": "npm run dev",
  "watch": ["src/*", "public/*"],
  "ext": "js, html, css, json"
}

• 參考文檔可以更多配置：https://github.com/remy/nodemon#nodemon

五、使用ES Lint做代碼風(fēng)格掃描

ES Lint是一款代碼風(fēng)格掃描工具，尤其是在團(tuán)隊(duì)開發(fā)時(shí)可以幫助我們規(guī)范我們的代碼風(fēng)格，并提供與IDE的集成做到代碼糾錯(cuò)。

• 安裝eslint npm i -D eslint
• 參考文檔：https://eslint.org/docs/user-guide/getting-started

六、在代碼提交時(shí)觸發(fā)指定操作

常常有這樣的場(chǎng)景，持續(xù)集成要求我們?cè)谔峤淮a之前測(cè)試在本地是可以通過(guò)的。這個(gè)時(shí)候我們可以在注冊(cè)“鉤子”的方式，在代碼提交之前在本地運(yùn)行測(cè)試，如果測(cè)試不通過(guò)則不允許提交。那么使用husky可以這一需求：

• husky文檔：https://github.com/typicode/husky#readme

例子1： 在git push 之前運(yùn)行測(cè)試

"husky": {
    "hooks": {
      "pre-push": "npm run coverage && npm run pact:test"
    }
  },

例子2： 在git commit 之前運(yùn)行代碼風(fēng)格檢查和自動(dòng)糾正

"husky": {
    "hooks": {
      "pre-commit": "npm lint"
    }
  },

七、開啟Gzip壓縮提高服務(wù)響應(yīng)速度

開啟gzip壓縮可以顯著提高HTTP的服務(wù)的訪問(wèn)速度，安裝compression中間件可以非常方便地啟用。

import compression from 'compression';
...
app.use(compression());