[[437443]]

【51CTO.com快譯】不可否認(rèn)，TypeScript憑著智能感知、靜態(tài)分析(又名“類型檢查”)、以及內(nèi)聯(lián)文檔等功能，已經(jīng)在J​​avaScript社區(qū)中占據(jù)了一席之地。這些功能雖然并非TypeScript獨(dú)有，但是能夠在如下方面提高開發(fā)團(tuán)隊(duì)的生產(chǎn)力，并改進(jìn)的代碼質(zhì)量：

• 通過(guò)實(shí)時(shí)的、自動(dòng)完成的代碼建議，實(shí)現(xiàn)更快的代碼編寫。
• 發(fā)現(xiàn)并提示代碼中的拼寫錯(cuò)誤。
• 方便新的成員熟悉代碼庫(kù)。
• 方便不同編程能力的團(tuán)隊(duì)成員更好地協(xié)作。
• 可以防止破損的代碼被自動(dòng)部署。
• 方便更加便捷、安全地修改和維護(hù)舊的代碼。
• 可用于項(xiàng)目的自動(dòng)文檔化。

下面，我將分不同的階段，向您深入淺出地介紹如何開啟TypeScript之旅。

階段 1：在JavaScript文件中啟用TypeScript

作為一種最為普及的代碼編輯器，Visual Studio Code被廣泛地用來(lái)編寫JavaScript。不過(guò)，VS Code也內(nèi)置了TypeScript，能夠提供上面提到的智能感知和自動(dòng)建議等基本功能。例如，我們可以創(chuàng)建一個(gè)帶有屬性hello的對(duì)象world。當(dāng)我們?cè)囍ピL問(wèn)該對(duì)象的屬性時(shí)，VS Code會(huì)自動(dòng)推薦hello。不僅如此，它還會(huì)告訴我們?cè)搶傩允且粋€(gè)字符串(string)類型。

這是一個(gè)非?；镜?shí)用的類型檢查。而且，就算代碼庫(kù)中存在少許錯(cuò)誤，這樣的類型檢查也能夠識(shí)別出來(lái)。例如，如果我們不小心將數(shù)字傳遞給了需要字符串類型的函數(shù)，那么就會(huì)被及時(shí)發(fā)現(xiàn)。因此，為了啟用針對(duì)JavaScript文件的全面類型檢查，您只需將注釋// @ts-check添加到待檢查的JavaScript文件的頂部便可。

據(jù)此，針對(duì)前面的例子，如果我們嘗試著用數(shù)字類型覆蓋對(duì)象的hello屬性，那么我們將會(huì)收到一條“Type ‘number’ is not assignable to type ‘string'”的警告。我們之前的函數(shù)之所以不會(huì)給出任何錯(cuò)誤提示，是因?yàn)門ypeScript并不知道輸入只能是字符串類型。為此，我們可以使用JSDoc向JavaScript添加各種類型。

此處的JSDoc是一個(gè)通過(guò)使用注釋，將上下文文檔添加到源代碼中的系統(tǒng)。它可以被用于自動(dòng)生成文檔站點(diǎn)。TypeScript支持解析JSDoc的各項(xiàng)注釋。對(duì)于前面的示例函數(shù)，我們可以告訴TypeScript，yell函數(shù)的第一個(gè)參數(shù)是str(字符串)類型，及該函數(shù)是一個(gè)“字符串”。

現(xiàn)在，當(dāng)我們向函數(shù)傳遞一個(gè)數(shù)字時(shí)，就會(huì)看到一個(gè)紅色的波浪形警告，而在將鼠標(biāo)懸停其上方時(shí)，會(huì)出現(xiàn)“Argument of type ‘number’ is not assignable to parameter of type ‘string’.”的具體警告內(nèi)容。您可以通過(guò)jsdoc.app，學(xué)習(xí)如何使用JSDoc記錄各項(xiàng)內(nèi)容。

階段 2：在JavaScript項(xiàng)目中啟用TypeScript

如果您處理的是大型JavaScript項(xiàng)目，那么逐一添加// @ts-check到每個(gè)文件中，顯然過(guò)于繁瑣。幸運(yùn)的是，VS Code提供了一些方法，來(lái)自動(dòng)化此類工作。其中的一種方法是將“Check JS”配置設(shè)置為true。也就是說(shuō)，我們?cè)趕ettings.json文件中設(shè)置為"javascript.implicitProjectConfig.checkJs": true。

如果您想在項(xiàng)目級(jí)別上為團(tuán)隊(duì)中彼此協(xié)作的每個(gè)人都啟用此功能，則可以通過(guò)將tsconfig.json文件添加到項(xiàng)目的根目錄來(lái)實(shí)現(xiàn)。有關(guān)tsconfig.json中各種配置選項(xiàng)的詳細(xì)信息，請(qǐng)參閱--https://www.staging-typescript.org/tsconfig。

JSON 
{ 
  "compilerOptions": { 
    "checkJs": true,               /* Report errors in .js files. */ 
  } 
} 

JSDocs支持許多內(nèi)置的類型，其中包括：string、number、boolean、array、promise、function等。不過(guò)，您可能需要?jiǎng)?chuàng)建某些超出基本定義的類型。例如，在定義一個(gè)“Dog”對(duì)象類型時(shí)，它需要具有“品種(breed)”、“年齡(age)”、以及可選的“名字(name)”屬性。那么，我們可以通過(guò)JSDoc來(lái)進(jìn)行如下類型的定義：

Plain Text 
/** 
 * @typedef {object} Dog 
 * @property {string} breed 
 * @property {number} age 
 * @property {string} [name] 
 */ 

除了這種通過(guò)語(yǔ)法的方式來(lái)定義對(duì)象以外，您還可以通過(guò)參閱JSDoc文檔，獲悉更多TypeScript的泛型和實(shí)用類型。

下面，我們來(lái)看如何使用types.js文件，來(lái)定義各種全局類型，并向代碼庫(kù)中導(dǎo)入類型定義。據(jù)此，我們將Dog的類型定義放入該文件中，通過(guò)引用相對(duì)路徑，實(shí)現(xiàn)在各種不同文件中導(dǎo)入并使用該類型：

JSON 
/** @type {import('./types).Dog} */ 
const myDog = { 
  breed: 'Chiweenie', 
  age: 4, 
  name: 'Nugget' 
} 

如果需要讓Dog能夠在同一個(gè)文件中的多處使用到該類型，我們則可以在本地重新定義類型，以減少輸入：

JSON 
/** @typedef {import('./types).Dog} Dog */ 
/** @type {Dog} */ 
const myDog = { 
  breed: 'Chiweenie', 
  age: 4, 
  name: 'Nugget' 
} 

您可能會(huì)發(fā)現(xiàn)，就目前而言，由于該文件不屬于JavaScript模塊，我們無(wú)法從types.js文件中導(dǎo)入任何內(nèi)容。編輯器會(huì)提示：“File ‘/path/to/types.js’ is not a module.”。對(duì)此，您可以使用CommonJS或ES模塊語(yǔ)法，導(dǎo)出該文件。其導(dǎo)出值并不重要，它甚至可以u(píng)ndefined。例如，它可以是下面的任何一行：

Plain Text 
// Works 
module.exports = {} 
// Sure 
exports.merp = '' 
// Why not? 
export default = null 
// Go for it 
export const thingamabob = undefined 

當(dāng)然，我們也可以是從第三方庫(kù)導(dǎo)入的類型定義。其語(yǔ)法雖然非常相似，但是并不會(huì)使用相對(duì)路徑，而是按照名稱去引用庫(kù)。例如，Vue.js(https://vuejs.org/)組件可以被輸入為：

Plain Text 
/** @type {import('vue').Component} */ 

當(dāng)然，并非所有庫(kù)都會(huì)提供類型定義。如果您的庫(kù)不提供類型定義，那么您可以去absolutetyped.org社區(qū)進(jìn)行檢索。VS Code有一個(gè)名為“自動(dòng)類型獲取(Automatic Type Acquisition)”的功能，會(huì)自動(dòng)為你查找和安裝來(lái)自社區(qū)的類型定義。

如果您愿意，也可以遵從上述語(yǔ)法，在TypeScript文件中編寫類型定義，不過(guò)其文件擴(kuò)展名為.ts。例如，如果想用TypeScript定義上述全局類型，我們可以將文件名更改為“type.ts”，其內(nèi)容如下：

TypeScript 
export interface Dog { 
  breed: string 
  age: number 
  name?: string 
} 

階段 3：將TypeScript集成到 CI/CD 管道中

下面，讓我們討論一些更為復(fù)雜的問(wèn)題。如果在代碼中引入了錯(cuò)誤，我們可以阻止代碼的部署嗎?在開始討論之前，我們假設(shè)：

• 您可以自如地使用命令行。
• 您對(duì)NPM已有一定的經(jīng)驗(yàn);如果沒有，可以通過(guò)鏈接--https://docs.npmjs.com/getting-started，了解NPM的相關(guān)基礎(chǔ)知識(shí)。
• 您已熟悉CI/CD(持續(xù)集成/持續(xù)交付)的概念。
• 您已經(jīng)擁有一個(gè)使用package.json文件初始化了的NPM項(xiàng)目。

我們的目標(biāo)是在CI/CD環(huán)境中運(yùn)行TypeScript編譯器，以便系統(tǒng)判定代碼是否存在類型錯(cuò)誤。為此，我們需要為CI/CD環(huán)境提供一個(gè)TypeScript版本，以及一個(gè)待運(yùn)行的腳本。

首先在終端里，我們需要在該項(xiàng)目的同一個(gè)文件夾中運(yùn)行如下命令：

npm install --save-devTypeScript 

它會(huì)在本地安裝TypeScript，并把Typecript包作為開發(fā)依賴項(xiàng)，包含在package.json文件中予以更新。在了解了有哪些依賴項(xiàng)已被安裝后，TypeScript可以在不依賴VS Code的情況下服務(wù)于該項(xiàng)目。接著，我們可以使用如下命令，更新package.json文件的NPM腳本部分：

Plain Text 
"ts": "tsc" 

上述命令會(huì)添加一個(gè)名為ts的新腳本，并運(yùn)行“tsc”命令(即typescript編譯器)。在運(yùn)行“npm run ts”命令之前，我們需要解決兩個(gè)問(wèn)題：

1. TypeScript需要知道待運(yùn)行文件的路徑。

2. TypeScript只適用于.ts文件，而我們只有.js文件。

對(duì)此，您需要決定是繼續(xù)編寫JavaScript文件呢，還是去寫TypeScript文件?就我而言，我認(rèn)為將所有內(nèi)容保留在JavaScript中會(huì)更加簡(jiǎn)單。畢竟TypeScript編譯器能夠很好地支持JavaScript文件，只不過(guò)未能在默認(rèn)情況下啟用罷了。

為了明確地告知TypeScript去檢查哪些文件，我們需要使用allowJs配置，來(lái)允許它在JavaScript文件上運(yùn)行。假設(shè)我們的JavaScript是寫在./src/index.js文件中的，那么我們將有如下選擇：

• 我們可以將“--allowJs ./src/index.js”添加到package.json文件中的NPM腳本中。
• 我們可以在每次調(diào)用NPM腳本：“npm run ts -- --allowJs ./src/index.js”時(shí)，添加上述命令。
• 我們可以在項(xiàng)目的根目錄中使用tsconfig.json文件。

由于我們已經(jīng)擁有一個(gè)tsconfig.json文件，因此可以直接使用它。同時(shí)，我們需要定義files數(shù)組，并將allowJs和noEmit設(shè)置為true：

JSON 
{ 
  "files": ["./src/index.js"], 
  "compilerOptions": { 
    "checkJs": true,               /* Report errors in .js files. */ 
    "allowJs": true,               /* Allow parsing javascript. */ 
    "noEmit": true,                /* Do not emit outputs. */ 
  } 
} 

由于TypeScript通常被用于轉(zhuǎn)譯代碼，因此我們可以在此將noEmit配置設(shè)置為true。這就意味著，它可以接受各種代碼，并以某種方式對(duì)其進(jìn)行轉(zhuǎn)換。例如，它能夠接收一個(gè)TypeScript文件，然后返回一個(gè)JavaScript文件。

運(yùn)行“npm run ts”命令，我們不會(huì)看到任何配置錯(cuò)誤，而只是一些與代碼相關(guān)的錯(cuò)誤。例如，在前面的示例中，如果我們?cè)噲D覆蓋被定義為字符串類型的屬性，就會(huì)產(chǎn)生錯(cuò)誤。

至此，我們已經(jīng)準(zhǔn)備好了將這種類型檢查，集成到自動(dòng)化部署的過(guò)程中。我們需要確保部署過(guò)程能夠順利地調(diào)用“npm run ts”命令。

值得一提的是，TypeScript雖然是一個(gè)很好的測(cè)試套件的補(bǔ)充，但它絕不是自動(dòng)化測(cè)試的替代品?？v然TypeScript可以消除進(jìn)入代碼庫(kù)時(shí)的各種類型錯(cuò)誤，但是如果您的項(xiàng)目依賴于自動(dòng)化部署的話，您還應(yīng)該做好單元或集成測(cè)試。

TypeScript雖然可能會(huì)阻止您在應(yīng)當(dāng)運(yùn)用數(shù)字的地方使用字符串，但是不會(huì)阻止您在只允許使用正數(shù)的情況下使用負(fù)數(shù)。因此，我建議您在系統(tǒng)中同時(shí)實(shí)施靜態(tài)分析和自動(dòng)化測(cè)試。而我最喜歡的JavaScript項(xiàng)目測(cè)試工具是Jest。

階段 4：為開源庫(kù)生成類型定義

definitelytyped.org之類的社區(qū)項(xiàng)目可以為TypeScript提供類型定義等支持。我們可以采用當(dāng)前的設(shè)置，而無(wú)需其他繁瑣的設(shè)置，讓TypeScript為我們的項(xiàng)目創(chuàng)建類型定義文件。在完成之后，我們可以發(fā)布自己的庫(kù)，以便用戶擁有豐富的類型定義，進(jìn)而協(xié)助改善用戶與庫(kù)交互的體驗(yàn)。

首先，我們需要對(duì)tsconfig.json文件進(jìn)行更多的修改。其中包括：刪除“noEmit”設(shè)置(或?qū)⑵湓O(shè)置為false)，將“declaration”和“emitDeclarationOnly”設(shè)置為true，并為“outDir”提供路徑。下面展示了新的文件內(nèi)容：

{ 
  "files": ["./src/index.js"], 
  "compilerOptions": { 
    "checkJs": true,               /* Report errors in .js files. */ 
    "allowJs": true,               /* Allow parsing javascript. */ 
    "declaration": true,           /* Generates '.d.ts' file. */ 
    "emitDeclarationOnly": true,   /* Only generate '.d.ts'. No JS */ 
    "outDir": "./dist",            /* Send output to this directory. */ 
  } 
} 

您可以為“outDir”任選一個(gè)路徑，以便為生成的類型定義文件提供存放之處。由于我們已經(jīng)使用了JavaScript，因此無(wú)需額外編譯步驟，便可將“emitDeclarationOnly”設(shè)置為true。在構(gòu)建步驟中，您也可以使用Babel.js和Rollup.js。

在生成了類型定義文件，并發(fā)送至/dist文件夾后，我們需要修改package.json文件，以便告知NPM各種文件的存在性，并讓任何使用庫(kù)的開發(fā)人員受益。為了在NPM處發(fā)布內(nèi)容，我們不但需要注意“name”和“version”屬性，還可以通過(guò)定義“types”(又名“typings”)屬性，來(lái)告知TypeScript在哪個(gè)文件夾中，查找?guī)斓念愋投x文件。當(dāng)然，如果您的類型定義文件(以.d.ts結(jié)尾)與代碼同處一個(gè)文件夾中，則無(wú)需上述設(shè)置。下面展示了package.json文件的示范性內(nèi)容：

{ 
  "name": "nuggetisthebest", 
  "version": "1.0.0", 
  "types": "dist", 
  "scripts": { 
    "ts": "tsc" 
  }, 
  "devDependencies": { 
    "typescript": "^4.1.3" 
  } 
} 

請(qǐng)參見NPM文檔，以獲悉更多有關(guān)如何將庫(kù)發(fā)布到NPM處。

禁止在某些代碼上運(yùn)行TypeScript

有時(shí)您在CI/CD管道中使用到了TypeScript，但并不希望它報(bào)告、甚至阻止項(xiàng)目的部署。對(duì)此，我們可以通過(guò)如下選項(xiàng)，來(lái)予以規(guī)避：

• 在某一行中禁用TypeScript：通過(guò)在任意行上添加注釋// @ts-ignore，您可以禁用TypeScript對(duì)于該行的分析。
• 在整個(gè)文件上禁用TypeScript：如果想禁用TypeScript對(duì)整個(gè)文件的檢查，您可以在文件的頂部添加注釋// @ts-nocheck。
• 在文件組或目錄組上禁用TypeScript：tsconfig.json文件有一個(gè)配置選項(xiàng)exclude，它允許您定義需要完全忽略的文件和目錄。

復(fù)雜類型

最終，您可能會(huì)需要重載函數(shù)(overloaded functions)之類非常復(fù)雜的類型定義。您可以在JSDoc中使用各種TypeScript功能，輕松地從TypeScript文件(.ts擴(kuò)展名)中導(dǎo)入相關(guān)的類型。

TypeScript 
/** @type { import('.types.ts').SomeType } */ 
const  someType  = {} 

這意味著在任何復(fù)雜的情況下，我們都可以使用常規(guī)的TypeScript文件，并將自定義類型導(dǎo)入到JSDoc中，而無(wú)需為整個(gè)項(xiàng)目編寫TypeScript。我們甚至都不需要依賴TypeScript編譯器。此外，我們還可以使用.d.ts文件，來(lái)聲明全局類型，具體請(qǐng)參見--https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html。

小結(jié)

總的說(shuō)來(lái)，雖然使用.ts文件比較常見，但是我會(huì)基于如下原因，去使用JSDocs方法：

• 無(wú)需額外的構(gòu)建步驟，只需普通的JavaScript。
• 可以將代碼復(fù)制并粘貼到任何JavaScript項(xiàng)目中。
• 并未增添新的語(yǔ)法，因此容易上手。
• 將更少的“噪音”引入代碼。
• 由于無(wú)需等待編譯器，因此開發(fā)的速度會(huì)更快。

下面是更多有關(guān)JSDoc的資源，可供您深入研究：

• 由VS Code提供的《Working with JavaScript》
• 由Devhints提供的《JSDoc Cheatsheet》
• 由Robert Biggs提供的《Type-Safe JavaScript with JSDoc》
• 由Robert Biggs提供的《JavaScript Type Linting》
• 由Stefan Baumgartner提供的《TypeScript without TypeScript – JSDoc superpowers》

原文標(biāo)題：Get Started With TypeScript the Easy Way，作者：Austin Gil

【51CTO譯稿，合作站點(diǎn)轉(zhuǎn)載請(qǐng)注明原文譯者和出處為51CTO.com】