在項目建立初期引入一些最佳實踐可以避免后期大量復雜的重構工作，本文總結了在使用Node JS構建Web服務時的一些最佳實踐，同時涉及的具體的操作步驟。
一、使用初始化腳手架
所謂腳手架，就是在初始化代碼庫時，腳手架可以幫助自動生成一些代碼和項目結構，注入一些框架。對于一個NodeJS項目，不需要我們從npm init初始化起，自己一步步安裝一些依賴。
Express命令
Express是目前最流行的NodeJS web框架。全局安裝一個express-generator，用來初始化express項目。
全局安裝命令：
npm install express-generator -g-
新建一個名為hello-express項目:
express hello-express
使用腳手架初始化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調試工具。
二、Swagger文檔服務
Swagger是一個最流行的的API構建與管理工具，在各種語言和框架都有相應的庫可以支持，同時安裝swagger-ui擴展進行API文檔管理和在線調試。
其遵循OpenAPI標準，OpenAPI定義了諸如路由轉發、參數定義與校驗等一整套API規范。
- OpenAPI規范文檔：https://swagger.io/specification/
- 在線API編輯器預覽：https://editor.swagger.io
發布swagger文檔
上面的swagger命令適合在本地編輯、調試使用，當在產品（Production）環境發布文檔服務時，適合引入 swagger UI 中間件
app.use(SwaggerUi(swaggerExpress.runner.swagger));
訪問http://localhost:10010/docs/#/即可查看API文檔：
- 完整代碼如下：
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語法
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 語法，以便能夠運行在當前和舊版本的瀏覽器或其他環境中。更多文檔可參考：https://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
參考資料
- 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
四、文件變動監聽并自動重啟服務
每次修改代碼時我們需要重啟Express來查看效果，nodemon可以在指定的文件發生修改后，幫助我們自動重啟服務，提高開發效率。
- 安裝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做代碼風格掃描
ES Lint是一款代碼風格掃描工具，尤其是在團隊開發時可以幫助我們規范我們的代碼風格，并提供與IDE的集成做到代碼糾錯。
- 安裝eslint
npm i -D eslint - 參考文檔：https://eslint.org/docs/user-guide/getting-started
六、在代碼提交時觸發指定操作
常常有這樣的場景，持續集成要求我們在提交代碼之前測試在本地是可以通過的。這個時候我們可以在注冊“鉤子”的方式，在代碼提交之前在本地運行測試，如果測試不通過則不允許提交。那么使用husky可以這一需求：
例子1： 在git push 之前運行測試
"husky": {
"hooks": {
"pre-push": "npm run coverage && npm run pact:test"
}
},
例子2： 在git commit 之前運行代碼風格檢查和自動糾正
"husky": {
"hooks": {
"pre-commit": "npm lint"
}
},
七、開啟Gzip壓縮提高服務響應速度
開啟gzip壓縮可以顯著提高HTTP的服務的訪問速度，安裝compression中間件可以非常方便地啟用。
import compression from 'compression';
...
app.use(compression());
