使用TypeScript改造構建工具及測試用例

最近的一段時間一直在搞TypeScript，一個巨硬出品、賦予JavaScript語言靜態型別和編譯的語言。
第一個完全使用TypeScript重構的純Node.js專案已經上線並穩定執行了。
第二個前後端的專案目前也在重構中，關於前端基於webpack的TypeScript套路之前也有提到過：TypeScript在react專案中的實踐。

但是這些做完以後也總感覺缺了點兒什麼 （沒有盡興）：

是的，依然有五分之一的JavaScript程式碼存在於專案中，作為一個TypeScript的示例專案，表現的很不純粹。
所以有沒有可能將這些JavaScript程式碼也換成TypeScript呢？
答案肯定是有的，首先需要分析這些程式碼都是什麼：

• Webpack打包時的配置檔案
• 一些簡單的測試用例（使用的mocha和chai）

知道了是哪些地方還在使用JavaScript，這件事兒就變得很好解決了，從構建工具（Webpack）開始，逐個擊破，將這些全部替換為TypeScript。

Webpack 的 TypeScript 實現版本

在這8102年，很幸福，Webpack官方已經支援了TypeScript編寫配置檔案，文件地址。
除了TypeScript以外還支援JSX和CoffeeScript的直譯器，在這就忽略它們的存在了

依賴的安裝

首先是要安裝TypeScript相關的一套各種依賴，包括直譯器及該語言的核心模組：

npm install -D typescript ts-node

typescript為這個語言的核心模組，ts-node用於直接執行.ts檔案，而不需要像tsc那樣會編譯輸出.js檔案。

ts-node helloworld.ts

因為要在TypeScript環境下使用Webpack相關的東東，所以要安裝對應的types。
也就是Webpack所對應的那些*.d.ts，用來告訴TypeScript這是個什麼物件，提供什麼方法。

npm i -D @types/webpack

一些常用的pLugin都會有對應的@types檔案，可以簡單的通過npm info @types/XXX來檢查是否存在

如果是一些小眾的plugin，則可能需要自己建立對應的d.ts檔案，例如我們一直在用的qiniu-webpack-plugin，這個就沒有對應的@types包的，所以就自己建立一個空檔案來告訴TypeScript這是個啥：

declare module `qiniu-webpack-plugin` // 就一個簡單的定義即可

// 如果還有其他的包，直接放到同一個檔案就行了
// 檔名也沒有要求，保證是 d.ts 結尾即可

放置的位置沒有什麼限制，隨便丟，一般建議放到types資料夾下

最後就是.ts檔案在執行時的一些配置檔案設定。
用來執行Webpack的.ts檔案對tsconfig.json有一些小小的要求。
compilerOptions下的target選項必須是es5，這個代表著輸出的格式。
以及module要求選擇commonjs。

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es5",
    "esModuleInterop": true
  }
}

但一般來講，執行Webpack的同級目錄都已經存在了tsconfig.json，用於實際的前端程式碼編譯，很可能兩個配置檔案的引數並不一樣。
如果因為要使用Webpack去修改真正的程式碼配置引數肯定是不可取的。
所以我們就會用到這麼一個包，用來改變ts-node執行時所依賴的配置檔案：tsconfig-paths

在Readme中發現了這樣的說法：If process.env.TS_NODE_PROJECT is set it will be used to resolved tsconfig.json。
在Webpack的文件中同樣也提到了這句，所以這是一個相容的方法，在命令執行時指定一個路徑，在不影響原有配置的情況下建立一個供Webpack打包時使用的配置。

1. 將上述的配置檔案改名為其它名稱，Webpack文件示例中為tsconfig-for-webpack-config.json，這裡就直接沿用了
2. 然後新增npm script如下

{
  "scripts": {
    "build": "TS_NODE_PROJECT=tsconfig-for-webpack-config.json webpack --config configs.ts"
  }
}

檔案的編寫

關於配置檔案，從JavaScript切換到TypeScript實際上並不會有太大的改動，因為Webpack的配置檔案大多都是寫死的文字/常量。
很多型別都是自動生成的，基本可以不用手動指定，一個簡單的示例：

import { Configuration } from `webpack`

const config: Configuration = {
  mode: process.env.NODE_ENV === `production` ? `production` : `development`,
}

export default config

Configuration是一個Webpack定義的介面（interface），用來規範一個物件的行為。
在VS Code下按住Command + 單擊可以直接跳轉到具體的webpack.d.ts定義檔案那裡，可以看到詳細的定義資訊。

各種常用的規則都寫在了這裡，使用TypeScript的一個好處就是，當要實現一個功能時你不再需要去網站上查詢應該要配置什麼，可以直接翻看d.ts的定義。
如果註釋寫得足夠完善，基本可以當成文件來用了，而且在VS Code編輯器中還有動態的提示，以及一些錯誤的糾正，比如上述的NODE_ENV的獲取，如果直接寫process.env.NODE_ENV || `development`是會丟擲一個異常的，因為從d.ts中可以看到，關於mode只有三個有效值production、developemnt和none，而process.env.NODE_ENV顯然只是一個字串型別的變數。

所以我們需要使用三元運算子保證傳入的引數一定是我們想要的。

以及在編寫的過程中，如果有一些自定義的plugin之類的，可能在使用的過程中會拋異常提示說某個物件不是有效的Plugin物件，一個很簡單的方法，在對應的plugin後邊新增一個as webpack.Plugin即可。

在這裡TypeScript所做的只是靜態的檢查，並不會對實際的程式碼執行造成任何影響，就算型別因為強行as而改變，也只是編譯期的修改，在實際執行的JavaScript程式碼中還是弱型別的

在完成了上述的操作後，再執行npm run XXX就可以直接執行TypeScript版本的Webpack配置咯。

探索期間的一件趣事

因為我的專案根目錄已經安裝了ts-node，而前端專案是作為其中的一個資料夾存在的，所以就沒有再次進行安裝。
這就帶來了一個令人吐血的問題。

首先全部流程走完以後，我直接在命令列中輸入TS_NODE_PROJECT=XXX.json NODE_ENV=dev webpack --config ./webpack/dev.ts
完美執行，然後將這行命令放到了npm scripts中：

{
  "scripts": {
    "start": "TS_NODE_PROJECT=XXX.json NODE_ENV=dev webpack --config ./webpack/dev.ts"
  }
}

再次執行npm start，發現竟然出錯了-.-，提示我說import語法不能被識別，這個很顯然就是沒有應用我們在ts_NODE_PROJECT中指定的config檔案。
剛開始並不知道問題出在哪，因為這個在命令列中直接執行並沒有任何問題。
期間曾經懷疑是否是環境變數沒有被正確設定，還使用了cross-env這個外掛，甚至將命令寫到了一個sh檔案中進行執行。
然而問題依然存在，後來在一個群中跟小夥伴們聊起了這個問題，有人提出，你是不是全域性安裝了ts-node。
檢查以後發現，果然是的，在命令列執行時使用的是全域性的ts-node，但是在npm scripts中使用的是本地的ts-node。
在命令列環境執行時還以為是會自動尋找父資料夾node_modules下邊的依賴，其實是使用的全域性包。
乖乖的在client-src資料夾下也安裝了ts-node就解決了這個問題。
全域性依賴害人。。

測試用例的改造

前邊的Webpack改為TypeScript大多數原因是因為強迫症所致。
但是測試用例的TypeScript改造則是一個能極大提高效率的操作。

為什麼要在測試用例中使用 TypeScript

測試用例使用chai來編寫，（之前的Postman也是用的chai的語法）
chai提供了一系列的語義化鏈式呼叫來實現斷言。
在之前的分享中也提到過，這麼多的命令你並不需要完全記住，只知道一個expect(XXX).to.equal(true)就夠了。

但是這樣的通篇to.equal(true)是巨醜無比的，而如果使用那些語義化的鏈式呼叫，在不熟練的情況下很容易就會得到：

Error: XXX.XXX is not a function

因為這確實有一個門檻問題，必須要寫很多才能記住呼叫規則，各種not、includes的操作。
但是接入了TypeScript以後，這些問題都迎刃而解了。
也是前邊提到的，所有的TypeScript模組都有其對應的.d.ts檔案，用來告訴我們這個模組是做什麼的，提供了什麼可以使用。
也就是說在測試用例編寫時，我們可以通過動態提示來快速的書寫斷言，而不需要結合著文件去進行“翻譯”。

使用方式

如果是之前有寫過mocha和chai的童鞋，基本上修改檔案字尾+安裝對應的@types即可。
可以直接跳到這裡來：開始編寫測試指令碼
但是如果對測試用例感興趣，但是並沒有使用過的童鞋，可以看下邊的一個基本步驟。

安裝依賴

1. TypeScript相關的安裝，npm i -D typescript ts-node
2. Mocha、chai相關的安裝，npm i -D mocha chai @types/mocha @types/chai
3. 如果需要涉及到一些API的請求，可以額外安裝chai-http，npm i -D chai-http @types/chai-http

環境的依賴就已經完成了，如果額外的使用一些其他的外掛，記得安裝對應的@types檔案即可。
如果有使用ESLint之類的外掛，可能會提示modules必須存在於dependencies而非devDependencies
這是ESLint的import/no-extraneous-dependencies規則導致的，針對這個，我們目前的方案是新增一些例外：

import/no-extraneous-dependencies:
  - 2
  - devDependencies:
    - "**/*.test.js"
    - "**/*.spec.js"
    - "**/webpack*"
    - "**/webpack/*"

針對這些目錄下的檔案/資料夾不進行校驗。是的，webpack的使用也會遇到這個問題

開始編寫測試指令碼

如果是對原有的測試指令碼進行修改，無外乎修改字尾、新增一些必要的型別宣告，不會對邏輯造成任何修改。

一個簡單的示例

// number-comma.ts
export default (num: number | string) => String(num).replace(/B(?=(d{3})+$)/g, `,`)

// number-comma.spec.ts
import chai from `chai`
import numberComma from `./number-comma`

const { expect } = chai

// 測試項
describe(`number-comma`, () => {
  // 子專案1
  it(``1234567` should transform to `1,234,567``, done => {
    expect(numberComma(1234567)).to.equal(`1,234,567`)
    done()
  })

  // 子專案2
  it(``123` should never transform`, done => {
    const num = 123
    expect(numberComma(num)).to.equal(String(num))
    done()
  })
})

如果全域性沒有安裝mocha，記得將命令寫到npm script中，或者通過下述方式執行

./node_modules/mocha/bin/mocha -r ts-node/register test/number-comma.spec.ts

# 如果直接這樣寫，會丟擲異常提示 mocha 不是命令
mocha -r ts-node/register test/number-comma.spec.ts

mocha有一點兒比較好的是提供了-r命令來讓你手動指定執行測試用例指令碼所使用的直譯器，這裡直接設定為ts-node的路徑ts-node/register，然後就可以在後邊直接跟一個檔名（或者是一些萬用字元）。

目前我們在專案中批量執行測試用例的命令如下：

{
  "scripts": {
    "test": "mocha -r ts-node/register test/**/*.spec.ts"
  }
}

npm test可以直接呼叫，而不需要新增run命令符，類似的還有start、build等等

一鍵執行以後就可以得到我們想要的結果了，再也不用擔心一些程式碼的改動會影響到其他模組的邏輯了 （前提是認真寫測試用例）

小結

做完上邊兩步的操作以後，我們的專案就實現了100%的TypeScript化，在任何地方享受靜態編譯語法所帶來的好處。
附上更新後的程式碼含量截圖：

最近針對TypeScript做了很多事情，從Node.js、React以及這次的Webpack與Mocha+Chai。
TypeScript因為其存在一個編譯的過程，極大的降低了程式碼出bug的可能性，提高程式的穩定度。
全面切換到TypeScript更是能夠降低在兩種語法之間互相切換時所帶來的不必要的消耗，祝大家搬磚愉快。

之前關於 TypeScript 的筆記

• TypeScript在node專案中的實踐
• TypeScript在react專案中的實踐

一個完整的 TypeScript 示例

typescript-example

歡迎各位來討論關於TypeScript使用上的一些問題，針對穩重的感覺不足之處也歡迎指出。

參考資料

• ts-node
• configuration-languages | webpack
• mochajs
• chaijs