新建NodeJS Web項目的幾個最佳實踐

在項目創建初期引入一些最佳實踐能夠避免後期大量複雜的重構工做，本文總結了在使用Node JS構建Web服務時的一些最佳實踐，同時涉及的具體的操做步驟。

1、使用初始化腳手架

所謂腳手架，就是在初始化代碼庫時，腳手架能夠幫助自動生成一些代碼和項目結構，注入一些框架。對於一個NodeJS項目，不須要咱們從npm init初始化起，本身一步步安裝一些依賴。

Express命令

Express是目前最流行的NodeJS web框架。全局安裝一個express-generator，用來初始化express項目。

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

• 新建一個名爲hello-express項目: express hello-express

  

使用Swagger腳手架

當使用NodeJS 開發Web API時，強烈建議使用Swagger進行API構建與管理，以及提供API文檔服務。全局安裝swagger命令也能夠實現初始化一個swagger項目。swagger命令可讓你在瀏覽器上實時直接編輯你的API定義和調試API。

初始化swagger項目

• 安裝命令：npm install swagger -g
• 新建Swagger API項目：swagger project create hello-swagger，在這過程當中會讓你選擇使用哪一種Web服務器，當選擇express時就能夠自動引入express框架
• 項目結構：

.
├── 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
複製代碼

實時編輯和語法校驗

• 啓動在線編輯：swagger project edit, 此時會打開系統瀏覽器，在瀏覽器中能夠直接編輯swagger文檔，並進行實時語法檢查，同時瀏覽器裏面的編輯變動會回寫到代碼。

在線調試API

上圖右側部分，就是相似於 postman的API調試工具。

2、Swagger文檔服務

Swagger是一個最流行的的API構建與管理工具，在各類語言和框架都有相應的庫能夠支持，同時安裝swagger-ui擴展進行API文檔管理和在線調試。 其遵循OpenAPI標準，OpenAPI定義了諸如路由轉發、參數定義與校驗等一整套API規範。

• OpenAPI規範文檔：swagger.io/specificati…
• 在線API編輯器預覽：editor.swagger.io

發佈swagger文檔

上面的swagger命令適合在本地編輯、調試使用，當在產品（Production）環境發佈文檔服務時，適合引入 swagger UI 中間件

app.use(SwaggerUi(swaggerExpress.runner.swagger));
複製代碼

訪問http://localhost:10010/docs/#/便可查看API文檔：

• 在線預覽：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');
  }
});
複製代碼

3、啓用ES6 JS語法

ECMAScript 是 JS 的語言標準，ES6是新的JS語法標準。在沒有其它配置的狀況下使用ES6語法會出現一下錯誤。咱們須要引入babel作語法轉換。

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 是一個 JavaScript 編譯器，工具鏈，主要用於將 ECMAScript 2015+ 版本的代碼轉換爲向後兼容的 JavaScript 語法，以便可以運行在當前和舊版本的瀏覽器或其餘環境中。更多文檔可參考：www.babeljs.cn/docs/

如何配置？

• 安裝依賴：

npm install -D @babel/core @babel/cli @babel/preset-env @babel/node
複製代碼

• 在根目錄建立.babelrc文件，內容以下

{ 
  "presets": ["@babel/preset-env"] 
}
複製代碼

• 使用babel-node命令代替node

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

如何處理已有的非ES6項目？

安裝一個npm module cjs-to-es6 能夠作一些簡單的ES6語法轉化：

npm install -g cjs-to-es6
複製代碼

參考資料

• www.babeljs.cn/docs/
• How to enable ES6 (and beyond) syntax with Node and Express：medium.freecodecamp.org/how-to-enab…

4、文件變更監聽並自動重啓服務

每次修改代碼時咱們須要重啓Express來查看效果，nodemon能夠在指定的文件發生修改後，幫助咱們自動重啓服務，提升開發效率。

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

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

• 參考文檔能夠更多配置：github.com/remy/nodemo…

5、使用ES Lint作代碼風格掃描

ES Lint是一款代碼風格掃描工具，尤爲是在團隊開發時能夠幫助咱們規範咱們的代碼風格，並提供與IDE的集成作到代碼糾錯。

• 安裝eslint npm i -D eslint
• 參考文檔：eslint.org/docs/user-g…

6、在代碼提交時觸發指定操做

經常有這樣的場景，持續集成要求咱們在提交代碼以前測試在本地是能夠經過的。這個時候咱們能夠在註冊「鉤子」的方式，在代碼提交以前在本地運行測試，若是測試不經過則不容許提交。那麼使用husky能夠這一需求：

• husky文檔：github.com/typicode/hu…

例子1： 在git push 以前運行測試

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

例子2： 在git commit 以前運行代碼風格檢查和自動糾正

"husky": {
    "hooks": {
      "pre-commit": "npm lint"
    }
  },
複製代碼

7、開啓Gzip壓縮提升服務響應速度

開啓gzip壓縮能夠顯著提升HTTP的服務的訪問速度，安裝compression中間件能夠很是方便地啓用。

import compression from 'compression';
...
app.use(compression());
複製代碼