本文系原創(chuàng)，轉(zhuǎn)載請附帶作者信息：yhlben

項目地址：https://github.com/yhlben/cdfang-spider

前言

在實際的開發(fā)過程中，從零開始初始化一個項目往往很麻煩，所以各種各樣的腳手架工具應(yīng)運(yùn)而生。crea-react-app，vue-cli，@angular/cli 等腳手架工具，只需要執(zhí)行一個命令，項目結(jié)構(gòu)以及開發(fā)環(huán)境就搭建好了。

腳手架工具確實方便了我們使用，開發(fā)者可以專注于業(yè)務(wù)，而不需要考慮太多的環(huán)境搭建。但作者認(rèn)為，學(xué)習(xí)腳手架工具背后的搭建過程也是很重要的，以防腳手架掛了之后，我們還能正常搭建項目?；谶@個目的，作者從零搭建了cdfang-spider項目。

現(xiàn)在讓我們就以這個項目為例，從零開始搭建項目吧。

項目選型

1. 三大框架里選哪個？

   • react 個人愛好。
   • react-router 定義路由。
   • react context 狀態(tài)管理。
   • react hooks 組件化。

2. 引入強(qiáng)類型語言？

   • typescript。為 js 提供類型支持，編輯器友好，增加代碼可維護(hù)性，使用起來心里踏實。
   • 在使用第三方庫時，可以寫出更加符合規(guī)范的代碼，避免 api 亂用等。
   • 項目中依賴了大量 @types/xxx 包，無形中增加了項目體積。
   • 編輯器對 ts 文件進(jìn)行類型檢查，需要遍歷 node_modules 目錄下所有的 @types 文件，會造成編輯器卡頓現(xiàn)象。
   • 目前仍然存在很多庫沒有 @types 支持，使用起來并不方便。

3. css 選型？

   • 預(yù)編譯器 less。項目中使用了變量定義，選擇器嵌套，選擇器復(fù)用等，less 夠用了。
   • 解決命名沖突可以使用 css modules，暫未考慮 css in js。
   • 使用 bem 命名規(guī)范。
   • 使用 postcss 插件 autoprefixer，增加 css 兼容性。

4. 構(gòu)建工具選哪個？

   • webpack。內(nèi)置 tree shaking，scope hosting 等，打包效率高，社區(qū)活躍。
   • webpack-merge 合并不同環(huán)境配置文件。
   • 配置 externals。引入 cdn 代替 node_modules 中體積較大的包。
   • gulp。用來打包 node 端代碼。

5. 代碼規(guī)范檢查？

   • eslint。輔助編碼規(guī)范執(zhí)行，有效控制代碼質(zhì)量。同時也支持校驗 typescript 語法。
   • 配置 eslint-config-airbnb 規(guī)則。
   • 配置 eslint-config-prettier 關(guān)閉和 prettier 沖突的規(guī)則。

6. 測試框架選型？

   • jest。大而全，包含：測試框架，斷言庫，mock 數(shù)據(jù)，覆蓋率等。
   • enzyme。測試 react 組件。

7. 后端框架選型？

   • koa。精簡好用，中間件機(jī)制強(qiáng)大。
   • apollo-server。幫助搭建 graphQL 后端環(huán)境。

8. 數(shù)據(jù)庫選型？

   • mongodb。類 json 的存錯格式，方便存儲，前端友好。
   • 配置 mongoose，方便給 mongodb 數(shù)據(jù)庫建模。

9. 接口方式選型？

   • graphql?？梢愿鶕?jù)需要格式獲取對應(yīng)數(shù)據(jù)，減少接口冗余數(shù)據(jù)。
   • graphql schema 定義了后端接口的參數(shù)，操作和返回類型，從此不需要提供接口文檔。
   • 前端可以在 schema 定義后開始開發(fā)，數(shù)據(jù)格式自己掌握。
   • schema 可拼接?？梢越M合和連接多個 graphql api，進(jìn)行級聯(lián)查詢等。
   • 社區(qū)友好，有很多優(yōu)秀的庫可以直接使用： apollo，relay 等。

基本框架選型完畢，接下來就開始搭建項目環(huán)境。

搭建 TypeScript 環(huán)境

TypeScript 是 JavaScript 的超集，意味著可以完全兼容 JavaScript 文件，但 TypeScript 文件卻并不能直接在瀏覽器中運(yùn)行，需要經(jīng)過編譯生成 JavaScript 文件后才能運(yùn)行。

1、 新建 tsconfig.json 文件。

• tsc -init 生成初始化 tsconfig.json 文件。
• vscode 會根據(jù) tsconfig.json 文件，進(jìn)行動態(tài)類型檢查，語法錯誤提示等。
• tsc 命令會根據(jù) tsconfig.json 文件配置的規(guī)則，將 ts 代碼轉(zhuǎn)換為 js 代碼。
• tslint 會讀取 tsconfig.json 文件中的規(guī)則，輔助編碼規(guī)范校驗。
  • tslint 官宣會被廢棄，后將被 eslint 代替。
  • eslint 同樣會用到 tsconfig.json 文件中的內(nèi)容。

2、 配置 eslint。

根據(jù) typescript-eslint 引導(dǎo)，配置 eslint 對 typescript 的支持。

• @typescript-eslint/parser 解析 ts 語法。
• @typescript-eslint/eslint-plugin 為 ts 文件應(yīng)用 eslint 和 tslint 規(guī)則。

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

使用 babel。好處如下：

• babel 社區(qū)有許多非常好的插件，babel-preset-env 可以支持到具體兼容瀏覽器的版本號，而 tsc 編譯器沒這個功能。
• babel 可以同時支持編譯 js 和 ts，所以沒必要在引入 tsc 編譯 ts 文件，只管理一個編譯器，可維護(hù)性更高。
• babel 編譯速度更快。tsc 編譯器需要遍歷所有類型定義文件（*.d.ts），包括 node_modules 里的，以確保代碼中正確地使用，type 太多會造成卡頓。

babel 流程分析

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

• 解析階段：將 js 代碼解析為抽象語法樹（ast）。
• 轉(zhuǎn)換階段：對 ast 進(jìn)行修改，產(chǎn)生一個轉(zhuǎn)換后的 ast。
• 輸出階段：將轉(zhuǎn)換后的 ast 輸出成 js 文件。

plugin 和 preset

• plugin: 解析，轉(zhuǎn)換，并輸出轉(zhuǎn)換后的 js 文件。例如：@babel/plugin-proposal-object-rest-spread 會輸出支持{...}解構(gòu)語法的 js 文件。
• preset: 是一組組合好的 plugin 集合。例如：@babel/preset-env 讓代碼支持最新的 es 語法，自動引入需要支持新特性的 plugin。

4、搜集所有的 ts，tsx 頁面（前端環(huán)境使用 webpack，node 項目使用 gulp），然后通過 babel 編譯成 js 文件。

搭建 React 環(huán)境

React 是一個庫，基于組件式開發(fā)，開發(fā)時常常需要用到以下語法：

• es6 模塊化。
• jsx 語法。
• typescript 語法。
• css 預(yù)處理器。

這些語法在目前瀏覽器中并不能直接執(zhí)行，需要進(jìn)行打包編譯，這也是搭建 React 環(huán)境的主要工作。

具體步驟

1、新建一個 html 文件，并在 body 中創(chuàng)建一個根節(jié)點(diǎn)，用于掛載 react 最后生成的 dom。

2、新建一個 index.tsx 文件，用于將項目中的所有組件，引入進(jìn)來，并調(diào)用 render 方法，將組件渲染到根節(jié)點(diǎn)中。

3、React 項目分層。

• containers 目錄，存放單獨(dú)的頁面
• components 目錄，存放的是組件，一個組件包含 jsx 和 css 兩個部分。
• context 目錄，存放公用的 react context。
• config 目錄，存放公共配置文件。
• utils 目錄，公用的函數(shù)組件庫。
• constants 目錄，存放靜態(tài)變量。

4、配置 webpack，以 index.tsx 為入口文件，進(jìn)行打包編譯。

• 由于不同環(huán)境的打包方式并不相同，這里抽象出開發(fā)環(huán)境、上線環(huán)境、優(yōu)化環(huán)境的配置文件，使用 webpack-merge 合并配置文件。
• 配置 css 預(yù)處理器，使用 less-loader。
• 配置 ts 編譯器，使用 babel-loader。
  • @babel/preset-env：編譯最新的 es 語法。
  • @babel/preset-react：編譯 react 語法。
  • @babel/preset-typescript：轉(zhuǎn)換 typescript 語法。
• 配置 url-loader，打包項目中的圖片資源。
• 配置 html-webpack-plugin 將最后生成的 js，css，注入第 1 步的 html 中。
  • 使用 ejs 模板配置開發(fā)環(huán)境和線上環(huán)境引入的 cdn。
• 開發(fā)環(huán)境配置，使用開箱即用的 webpack-dev-server。
  • webpack-dev-server 可以自動監(jiān)聽文件修改，自動刷新頁面，以及默認(rèn) source-map 等功能。
  • 配置熱模塊替換，react-hot-loader。

webpack 打包原理

webpack 打包過程就像是一條流水線，從入口文件開始，搜集項目中所有文件的依賴關(guān)系，如果遇到不能夠識別的模塊，就使用對應(yīng)的 loader 轉(zhuǎn)換成能夠識別的模塊。webpack 還能使用 plugin 在流水線生命周期中掛載自定義事件，來控制 webpack 輸出結(jié)果。

5、編寫 npm script，一鍵開啟開發(fā)模式。

// cross-env 用來跨環(huán)境設(shè)置環(huán)境變量
"scripts": {
  "dev:client": "cross-env NODE_ENV=development webpack-dev-server --open"
}

6、現(xiàn)在運(yùn)行 npm run dev:client 就可以愉快地編寫客戶端代碼了。

搭建 NodeJs 環(huán)境

由于 node 端使用了 typescript 和最新的 es 語法，所以需要進(jìn)行打包編譯。

• 配置 gulp，遍歷每一個 ts 文件，調(diào)用 gulp-babel，將 ts 代碼轉(zhuǎn)換成 js 代碼。
• 配置 supervisor 自動重啟 node 服務(wù)（nodemon 對于不存在的目錄不能進(jìn)行監(jiān)控）。
• 編寫 npm script 一鍵啟動 node 端開發(fā)環(huán)境。

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

配置好 gulp 后，就可以運(yùn)行 npm run dev:server 一鍵啟動服務(wù)器端開發(fā)環(huán)境。

層次結(jié)構(gòu)劃分

項目采用傳統(tǒng)的 mvc 模式進(jìn)行層次劃分。

Model 層

Model 層的主要工作：連接數(shù)據(jù)庫，封裝數(shù)據(jù)庫操作，例如：新增數(shù)據(jù)、刪除數(shù)據(jù)、查詢數(shù)據(jù)、更新數(shù)據(jù)等。

• 新建 model 文件夾，目錄下的每一個文件對應(yīng)數(shù)據(jù)庫的一個表。
• model 文件中包含對一個數(shù)據(jù)表的增刪改查操作。
  • 使用 mongoose 更方便地對 mongodb 數(shù)據(jù)庫進(jìn)行讀寫操作。
• model 文件返回封裝好的對象，提供給 controller 層使用。

Controller 層

Controller 層的主要工作：接收和發(fā)送 http 請求。根據(jù)前端請求，調(diào)用 model 層獲取數(shù)據(jù)，再返回給前端。

傳統(tǒng)的后端一般還包含 service 層，專門用來處理業(yè)務(wù)邏輯。

• 根據(jù)前端請求，找到對應(yīng)的 model 層獲取數(shù)據(jù)，經(jīng)過加工處理后，返回給前端。
• 編寫中間件，記錄系統(tǒng)日志，錯誤處理，404 頁面等。
• 支持前端 react-router 中的 BrowserRouter。根據(jù)前端路由，后端配置對應(yīng)的路由，匹配結(jié)果為 index.html 文件。
• 項目中使用的 graphql 比較基礎(chǔ)，也直接放在了 controller 層進(jìn)行處理。

View 層

View 層的主要工作：提供前端頁面模板。如果是服務(wù)器端渲染，是將 model 層的數(shù)據(jù)注入到 view 層中，最后通過 controller 層返回給客戶端。由于本項目前端使用 react 渲染，所以 view 層直接是經(jīng)過 webpack 打包后的頁面。

• 使用 koa-static 提供一個靜態(tài)文件服務(wù)器，用來訪問前端打包后生成的 html 文件。

搭建 GraphQL 環(huán)境

GraphQL 是一種用于 api 的查詢語言，需要服務(wù)器端配置 graphql 支持，同時也需要客戶端使用 graphql 語法的格式進(jìn)行請求。

使用 apollo 更快的搭建 graphql 環(huán)境。

• 服務(wù)器端配置 apollo-server。
  • 使用 schema，定義請求的類型，返回的格式。
  • 使用 resolvers 來處理對應(yīng)的 schema。
• 客戶端配置 apollo-client。
  • 按照 apollo-server 定義的 schema，來請求數(shù)據(jù)。

搭建 MongoDB 環(huán)境

MongoDB 是一個面向文檔存儲的數(shù)據(jù)庫，操作起來十分簡單。

Mongoose 為 mongodb 提供了一種直接的，基于 scheme 結(jié)構(gòu)去定義你的數(shù)據(jù)模型。它內(nèi)置數(shù)據(jù)驗證，查詢構(gòu)建，業(yè)務(wù)邏輯鉤子等，開箱即用。

• 使用 mongoose 建立和本地 mongodb 的連接。
• 創(chuàng)建 model 模型，一個模型對應(yīng) mongodb 里的一張表。
• 根據(jù) model 封裝增刪改查功能，并返回給 controller 層使用。

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

搭建測試環(huán)境

本項目使用 jest 作為測試框架，jest 包含了斷言庫、測試框架、mock 數(shù)據(jù)等功能，是一個大而全的測試庫。由于前端使用了 react 項目，這里引入了專門用來測試 react 的 enzyme 庫。

1、新建 jest.config.js 文件。

• 配置初始化 setup.ts 文件。
  • 根據(jù) react 版本配置對應(yīng)的 enzyme-adapter。
  • mock 全局變量，如 fech，canvas 等。
• 配置需要測試的文件。
• 配置 mock 數(shù)據(jù)文件。
• 配置測試文件的編譯方式。
  • ts 代碼使用 ts-jest 編譯。
• 配置代碼覆蓋率文件。

2、編寫測試文件。

• 新建__mocks__，__tests__目錄，存放測試文件和 mock 數(shù)據(jù)文件。
• 按照 src 中的目錄，建立相應(yīng)的測試文件目錄。

3、編寫測試腳本和上傳覆蓋率腳本。

"scripts": {
  "test": "jest --no-cache --colors --coverage --forceExit --detectOpenHandles",
  "coverage": "codecov"
}

配置上線環(huán)境

安裝好各種環(huán)境之后，接下來就要考慮項目上線了。

配置服務(wù)器環(huán)境

• 安裝 nodejs 環(huán)境。nvm 安裝 node
• 安裝 pm2 進(jìn)程守護(hù)。npm i pm2 -g
• 安裝 mongodb。mongodb 官方文檔
• 安裝免費(fèi) https 證書。letsencrypt 官網(wǎng)
  • 域名需要先進(jìn)行備案（使用阿里云備案，資料準(zhǔn)備齊全的話 10 天左右就可以批下來）。

代碼發(fā)布

本項目發(fā)布非常簡單，只需要一步操作就搞定了，這些都是經(jīng)過持續(xù)集成配置后的結(jié)果。

# 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 層，和后端綁定在一起。
  • 其他靜態(tài)資源，在 webpack 打包后自動上傳到七牛 cdn，使用 qiniu-upload-plugin 來進(jìn)行一鍵上傳。
• 打包服務(wù)器端代碼。

上述事情通過創(chuàng)建 npm script 就可以了完成需求了，但這些命令也不應(yīng)該每次都由手工敲一遍，通過配置 travisCI，每一次 master 分支提交代碼時，自動運(yùn)行上述命令就行了。

travisCI 配置

travisCI 是一個持續(xù)集成平臺，每當(dāng) github 提交代碼時，travisCI 就會得到通知，然后根據(jù) travisCI 中的配置信息執(zhí)行相應(yīng)的操作，并及時把運(yùn)行結(jié)果反饋給用戶。travisCI 配置文件可以參考項目根目錄下的 .travis.yml 文件。配置文件核心在于 script 的配置。

script:
  - npm run build
  - npm run test
after_success: npm run coverage

可以看到，每一次 github 提交后，travisCI 就會執(zhí)行 名稱為 build 的任務(wù)，任務(wù)分為 2 個步驟，首先執(zhí)行 build 命令，然后執(zhí)行 test 命令，當(dāng)命令都執(zhí)行完成后，執(zhí)行 coverage 命令。如果執(zhí)行命令期間出現(xiàn)任何錯誤，travisCI 會通過郵件及時通知我們。真正要上線時，先查看 ci 狀態(tài)，如果已通過所有的步驟，那就不用擔(dān)心發(fā)布的代碼有問題了。

總結(jié)

至此，整個項目選型與搭建流程已經(jīng)介紹完畢了，當(dāng)然還有一些很細(xì)節(jié)的地方?jīng)]有寫進(jìn)去，如果有不太明白的地方，可以提 issue，或者加我微信 yhl2016226。

接下來對以下 4 個方面寫個小總結(jié)。

• 開發(fā)方面：項目將前端、后端、數(shù)據(jù)庫端連通起來，組合成了一個小全棧的項目，加深了我對整個開發(fā)環(huán)節(jié)的理解。
• 測試方面：通過編寫單元測試，ui 測試，api 測試，積累了自動化測試方面的經(jīng)驗。
• 運(yùn)維方面：通過配置持續(xù)集成，守護(hù)進(jìn)程，nginx，https 等，讓我有能力實現(xiàn)小型項目的部署。
• 技術(shù)方面：項目中使用了一些比較新的技術(shù)，如：hooks api，graphql 等，但用的都很基礎(chǔ)，主要是為了練手，后續(xù)還得深入學(xué)習(xí)。

對于項目后期更新，主要是基于以下幾個方面：graphql，docker，k8s，微服務(wù)，serverless 等，東西太多，還得加油學(xué)習(xí)啊，??

參考鏈接

• TypeScript 和 Babel
• 前端決策樹