手搭一個 React，Typescript，Koa，GraphQL 環境

本文系原創，轉載請附帶作者資訊：yhlben

專案地址：github.com/yhlben/cdfa…

前言

在實際的開發過程中，從零開始初始化一個專案往往很麻煩，所以各種各樣的腳手架工具應運而生。crea-react-app，vue-cli，@angular/cli 等腳手架工具，只需要執行一個命令，專案結構以及開發環境就搭建好了。

腳手架工具確實方便了我們使用，開發者可以專注於業務，而不需要考慮太多的環境搭建。但作者認為，學習腳手架工具背後的搭建過程也是很重要的，以防腳手架掛了之後，我們還能正常搭建專案。基於這個目的，作者從零搭建了cdfang-spider專案。

現在讓我們就以這個專案為例，從零開始搭建專案吧。

專案選型

1. 三大框架裡選哪個？

   • react 個人愛好。
   • react-router 定義路由。
   • react context 狀態管理。
   • react hooks 元件化。

2. 引入強型別語言？

   • typescript。為 js 提供型別支援，編輯器友好，增加程式碼可維護性，使用起來心裡踏實。
   • 在使用第三方庫時，可以寫出更加符合規範的程式碼，避免 api 亂用等。
   • 專案中依賴了大量 @types/xxx 包，無形中增加了專案體積。
   • 編輯器對 ts 檔案進行型別檢查，需要遍歷 node_modules 目錄下所有的 @types 檔案，會造成編輯器卡頓現象。
   • 目前仍然存在很多庫沒有 @types 支援，使用起來並不方便。

3. css 選型？

   • 預編譯器 less。專案中使用了變數定義，選擇器巢狀，選擇器複用等，less 夠用了。
   • 解決命名衝突可以使用 css modules，暫未考慮 css in js。
   • 使用 bem 命名規範。
   • 使用 postcss 外掛 autoprefixer，增加 css 相容性。

4. 構建工具選哪個？

   • webpack。內建 tree shaking，scope hosting 等，打包效率高，社群活躍。
   • webpack-merge 合併不同環境配置檔案。
   • 配置 externals。引入 cdn 代替 node_modules 中體積較大的包。
   • gulp。用來打包 node 端程式碼。

5. 程式碼規範檢查？

   • eslint。輔助編碼規範執行，有效控制程式碼質量。同時也支援校驗 typescript 語法。
   • 配置 eslint-config-airbnb 規則。
   • 配置 eslint-config-prettier 關閉和 prettier 衝突的規則。

6. 測試框架選型？

   • jest。大而全，包含：測試框架，斷言庫，mock 資料，覆蓋率等。
   • enzyme。測試 react 元件。

7. 後端框架選型？

   • koa。精簡好用，中介軟體機制強大。
   • apollo-server。幫助搭建 graphQL 後端環境。

8. 資料庫選型？

   • mongodb。類 json 的存錯格式，方便儲存，前端友好。
   • 配置 mongoose，方便給 mongodb 資料庫建模。

9. 介面方式選型？

   • graphql。可以根據需要格式獲取對應資料，減少介面冗餘資料。
   • graphql schema 定義了後端介面的引數，操作和返回型別，從此不需要提供介面文件。
   • 前端可以在 schema 定義後開始開發，資料格式自己掌握。
   • schema 可拼接。可以組合和連線多個 graphql api，進行級聯查詢等。
   • 社群友好，有很多優秀的庫可以直接使用： apollo，relay 等。

基本框架選型完畢，接下來就開始搭建專案環境。

搭建 TypeScript 環境

TypeScript 是 JavaScript 的超集，意味著可以完全相容 JavaScript 檔案，但 TypeScript 檔案卻並不能直接在瀏覽器中執行，需要經過編譯生成 JavaScript 檔案後才能執行。

1、 新建 tsconfig.json 檔案。

• tsc -init 生成初始化 tsconfig.json 檔案。
• vscode 會根據 tsconfig.json 檔案，進行動態型別檢查，語法錯誤提示等。
• tsc 命令會根據 tsconfig.json 檔案配置的規則，將 ts 程式碼轉換為 js 程式碼。
• tslint 會讀取 tsconfig.json 檔案中的規則，輔助編碼規範校驗。
  • tslint 官宣會被廢棄，後將被 eslint 代替。
  • eslint 同樣會用到 tsconfig.json 檔案中的內容。

2、 配置 eslint。

根據 typescript-eslint 引導，配置 eslint 對 typescript 的支援。

• @typescript-eslint/parser 解析 ts 語法。
• @typescript-eslint/eslint-plugin 為 ts 檔案應用 eslint 和 tslint 規則。

3、 選擇一個 typescript 編譯器，tsc 還是 babel？

使用 babel。好處如下：

• babel 社群有許多非常好的外掛，babel-preset-env 可以支援到具體相容瀏覽器的版本號，而 tsc 編譯器沒這個功能。
• babel 可以同時支援編譯 js 和 ts，所以沒必要在引入 tsc 編譯 ts 檔案，只管理一個編譯器，可維護性更高。
• babel 編譯速度更快。tsc 編譯器需要遍歷所有型別定義檔案（*.d.ts），包括 node_modules 裡的，以確保程式碼中正確地使用，type 太多會造成卡頓。

babel 流程分析

babel 是一個 js 語法編譯器，在編譯時分為 3 個階段：解析、轉換、輸出。

• 解析階段：將 js 程式碼解析為抽象語法樹（ast）。
• 轉換階段：對 ast 進行修改，產生一個轉換後的 ast。
• 輸出階段：將轉換後的 ast 輸出成 js 檔案。

plugin 和 preset

• plugin: 解析，轉換，並輸出轉換後的 js 檔案。例如：@babel/plugin-proposal-object-rest-spread 會輸出支援{...}解構語法的 js 檔案。
• preset: 是一組組合好的 plugin 集合。例如：@babel/preset-env 讓程式碼支援最新的 es 語法，自動引入需要支援新特性的 plugin。

4、蒐集所有的 ts，tsx 頁面（前端環境使用 webpack，node 專案使用 gulp），然後通過 babel 編譯成 js 檔案。

搭建 React 環境

React 是一個庫，基於元件式開發，開發時常常需要用到以下語法：

• es6 模組化。
• jsx 語法。
• typescript 語法。
• css 前處理器。

這些語法在目前瀏覽器中並不能直接執行，需要進行打包編譯，這也是搭建 React 環境的主要工作。

具體步驟

1、新建一個 html 檔案，並在 body 中建立一個根節點，用於掛載 react 最後生成的 dom。

2、新建一個 index.tsx 檔案，用於將專案中的所有元件，引入進來，並呼叫 render 方法，將元件渲染到根節點中。

3、React 專案分層。

• containers 目錄，存放單獨的頁面
• components 目錄，存放的是元件，一個元件包含 jsx 和 css 兩個部分。
• context 目錄，存放公用的 react context。
• config 目錄，存放公共配置檔案。
• utils 目錄，公用的函式元件庫。
• constants 目錄，存放靜態變數。

4、配置 webpack，以 index.tsx 為入口檔案，進行打包編譯。

• 由於不同環境的打包方式並不相同，這裡抽象出開發環境、上線環境、優化環境的配置檔案，使用 webpack-merge 合併配置檔案。
• 配置 css 前處理器，使用 less-loader。
• 配置 ts 編譯器，使用 babel-loader。
  • @babel/preset-env：編譯最新的 es 語法。
  • @babel/preset-react：編譯 react 語法。
  • @babel/preset-typescript：轉換 typescript 語法。
• 配置 url-loader，打包專案中的圖片資源。
• 配置 html-webpack-plugin 將最後生成的 js，css，注入第 1 步的 html 中。
  • 使用 ejs 模板配置開發環境和線上環境引入的 cdn。
• 開發環境配置，使用開箱即用的 webpack-dev-server。
  • webpack-dev-server 可以自動監聽檔案修改，自動重新整理頁面，以及預設 source-map 等功能。
  • 配置熱模組替換，react-hot-loader。

webpack 打包原理

webpack 打包過程就像是一條流水線，從入口檔案開始，蒐集專案中所有檔案的依賴關係，如果遇到不能夠識別的模組，就使用對應的 loader 轉換成能夠識別的模組。webpack 還能使用 plugin 在流水線生命週期中掛載自定義事件，來控制 webpack 輸出結果。

5、編寫 npm script，一鍵開啟開發模式。

// cross-env 用來跨環境設定環境變數
"scripts": {
  "dev:client": "cross-env NODE_ENV=development webpack-dev-server --open"
}
複製程式碼

6、現在執行 npm run dev:client 就可以愉快地編寫客戶端程式碼了。

搭建 NodeJs 環境

由於 node 端使用了 typescript 和最新的 es 語法，所以需要進行打包編譯。

• 配置 gulp，遍歷每一個 ts 檔案，呼叫 gulp-babel，將 ts 程式碼轉換成 js 程式碼。
• 配置 supervisor 自動重啟 node 服務（nodemon 對於不存在的目錄不能進行監控）。
• 編寫 npm script 一鍵啟動 node 端開發環境。

"scripts": {
  "dev:server": "cross-env NODE_ENV=development gulp & cross-env NODE_ENV=development supervisor -i ./dist/client/ -w ./dist/ ./dist/app.js",
}
複製程式碼

配置好 gulp 後，就可以執行 npm run dev:server 一鍵啟動伺服器端開發環境。

層次結構劃分

專案採用傳統的 mvc 模式進行層次劃分。

Model 層

Model 層的主要工作：連線資料庫，封裝資料庫操作，例如：新增資料、刪除資料、查詢資料、更新資料等。

• 新建 model 資料夾，目錄下的每一個檔案對應資料庫的一個表。
• model 檔案中包含對一個資料表的增刪改查操作。
  • 使用 mongoose 更方便地對 mongodb 資料庫進行讀寫操作。
• model 檔案返回封裝好的物件，提供給 controller 層使用。

Controller 層

Controller 層的主要工作：接收和傳送 http 請求。根據前端請求，呼叫 model 層獲取資料，再返回給前端。

傳統的後端一般還包含 service 層，專門用來處理業務邏輯。

• 根據前端請求，找到對應的 model 層獲取資料，經過加工處理後，返回給前端。
• 編寫中介軟體，記錄系統日誌，錯誤處理，404 頁面等。
• 支援前端 react-router 中的 BrowserRouter。根據前端路由，後端配置對應的路由，匹配結果為 index.html 檔案。
• 專案中使用的 graphql 比較基礎，也直接放在了 controller 層進行處理。

View 層

View 層的主要工作：提供前端頁面模板。如果是伺服器端渲染，是將 model 層的資料注入到 view 層中，最後通過 controller 層返回給客戶端。由於本專案前端使用 react 渲染，所以 view 層直接是經過 webpack 打包後的頁面。

• 使用 koa-static 提供一個靜態檔案伺服器，用來訪問前端打包後生成的 html 檔案。

搭建 GraphQL 環境

GraphQL 是一種用於 api 的查詢語言，需要伺服器端配置 graphql 支援，同時也需要客戶端使用 graphql 語法的格式進行請求。

使用 apollo 更快的搭建 graphql 環境。

• 伺服器端配置 apollo-server。
  • 使用 schema，定義請求的型別，返回的格式。
  • 使用 resolvers 來處理對應的 schema。
• 客戶端配置 apollo-client。
  • 按照 apollo-server 定義的 schema，來請求資料。

搭建 MongoDB 環境

MongoDB 是一個面向文件儲存的資料庫，操作起來十分簡單。

Mongoose 為 mongodb 提供了一種直接的，基於 scheme 結構去定義你的資料模型。它內建資料驗證，查詢構建，業務邏輯鉤子等，開箱即用。

• 使用 mongoose 建立和本地 mongodb 的連線。
• 建立 model 模型，一個模型對應 mongodb 裡的一張表。
• 根據 model 封裝增刪改查功能，並返回給 controller 層使用。

接下來的步驟就是安裝 mongodb，啟動服務，就可以了。

搭建測試環境

本專案使用 jest 作為測試框架，jest 包含了斷言庫、測試框架、mock 資料等功能，是一個大而全的測試庫。由於前端使用了 react 專案，這裡引入了專門用來測試 react 的 enzyme 庫。

1、新建 jest.config.js 檔案。

• 配置初始化 setup.ts 檔案。
  • 根據 react 版本配置對應的 enzyme-adapter。
  • mock 全域性變數，如 fech，canvas 等。
• 配置需要測試的檔案。
• 配置 mock 資料檔案。
• 配置測試檔案的編譯方式。
  • ts 程式碼使用 ts-jest 編譯。
• 配置程式碼覆蓋率檔案。

2、編寫測試檔案。

• 新建__mocks__，__tests__目錄，存放測試檔案和 mock 資料檔案。
• 按照 src 中的目錄，建立相應的測試檔案目錄。

3、編寫測試指令碼和上傳覆蓋率指令碼。

"scripts": {
  "test": "jest --no-cache --colors --coverage --forceExit --detectOpenHandles",
  "coverage": "codecov"
}
複製程式碼

配置上線環境

安裝好各種環境之後，接下來就要考慮專案上線了。

配置伺服器環境

• 安裝 nodejs 環境。nvm 安裝 node
• 安裝 pm2 程式守護。npm i pm2 -g
• 安裝 mongodb。mongodb 官方文件
• 安裝免費 https 證照。letsencrypt 官網
  • 域名需要先進行備案（使用阿里雲備案，資料準備齊全的話 10 天左右就可以批下來）。

程式碼釋出

本專案釋出非常簡單，只需要一步操作就搞定了，這些都是經過持續整合配置後的結果。

# clone with Git Bash
git clone https://github.com/yhlben/cdfang-spider.git

# change directory
cd cdfang-spider

# install dependencies
npm i

# build for production with minification
npm run build
複製程式碼

所有的事情都在 build 命令下完成了，我們分析一下 npm run build 命令做的事情。

• eslint 語法錯誤檢查。
• 單元測試。
  • 上傳測試覆蓋率。
• 打包客戶端程式碼。
  • 打包後生成 html 檔案作為 node 端的 view 層，和後端繫結在一起。
  • 其他靜態資源，在 webpack 打包後自動上傳到七牛 cdn，使用 qiniu-upload-plugin 來進行一鍵上傳。
• 打包伺服器端程式碼。

上述事情通過建立 npm script 就可以了完成需求了，但這些命令也不應該每次都由手工敲一遍，通過配置 travisCI，每一次 master 分支提交程式碼時，自動執行上述命令就行了。

travisCI 配置

travisCI 是一個持續整合平臺，每當 github 提交程式碼時，travisCI 就會得到通知，然後根據 travisCI 中的配置資訊執行相應的操作，並及時把執行結果反饋給使用者。travisCI 配置檔案可以參考專案根目錄下的 .travis.yml 檔案。配置檔案核心在於 script 的配置。

script:
  - npm run build
  - npm run test
after_success: npm run coverage
複製程式碼

可以看到，每一次 github 提交後，travisCI 就會執行 名稱為 build 的任務，任務分為 2 個步驟，首先執行 build 命令，然後執行 test 命令，當命令都執行完成後，執行 coverage 命令。如果執行命令期間出現任何錯誤，travisCI 會通過郵件及時通知我們。真正要上線時，先檢視 ci 狀態，如果已通過所有的步驟，那就不用擔心釋出的程式碼有問題了。

總結

至此，整個專案選型與搭建流程已經介紹完畢了，當然還有一些很細節的地方沒有寫進去，如果有不太明白的地方，可以提 issue，或者加我微信 yhl2016226。

接下來對以下 4 個方面寫個小總結。

• 開發方面：專案將前端、後端、資料庫端連通起來，組合成了一個小全棧的專案，加深了我對整個開發環節的理解。
• 測試方面：通過編寫單元測試，ui 測試，api 測試，積累了自動化測試方面的經驗。
• 運維方面：通過配置持續整合，守護程式，nginx，https 等，讓我有能力實現小型專案的部署。
• 技術方面：專案中使用了一些比較新的技術，如：hooks api，graphql 等，但用的都很基礎，主要是為了練手，後續還得深入學習。

對於專案後期更新，主要是基於以下幾個方面：graphql，docker，k8s，微服務，serverless 等，東西太多，還得加油學習啊，?

參考連結

• TypeScript 和 Babel
• 前端決策樹