如何為你的JS項(xiàng)目添加智能提示與類型檢查詳解

前言

最近在做項(xiàng)目代碼重構(gòu)，其中有一個(gè)要求是為代碼添加智能提示和類型檢查。智能提示，英文為 IntelliSense，能為開(kāi)發(fā)者提供代碼智能補(bǔ)全、懸浮提示、跳轉(zhuǎn)定義等功能，幫助其正確并且快速完成編碼。說(shuō)起來(lái)，JavaScript 作為一門動(dòng)態(tài)弱類型解釋型語(yǔ)言，變量聲明后可以更改類型，并且類型在運(yùn)行時(shí)才能確定，由此容易產(chǎn)生大量代碼運(yùn)行中才能發(fā)現(xiàn)的錯(cuò)誤，相比 Java 等靜態(tài)類型語(yǔ)言，開(kāi)發(fā)體驗(yàn)上確實(shí)差了一截。更煩躁的是，智能提示就是依賴于靜態(tài)類型檢查的，所以在以前，指望 JavaScript 的智能提示完善度追上 Java 基本不可能。當(dāng)然，時(shí)代在進(jìn)步，TypeScript 已經(jīng)問(wèn)世許久，為 JavaScript 帶來(lái)了靜態(tài)類型檢查以及其他諸多特性。JavaScript 的智能提示也已有了解決方案。調(diào)研了一段時(shí)間后，下文以 VSCode 編輯器作為開(kāi)發(fā)工具，介紹一下如何為 JavaScript 加上智能提示以及類型檢查。

基于 JSDoc

JSDoc 是目前最通用的 JavaScript API 文檔生成器，根據(jù)其語(yǔ)法編寫代碼注釋，可以十分方便地自動(dòng)生成文檔。由于 JSDoc 能提供詳細(xì)的類型信息，其也被 VSCode 等編輯器接受應(yīng)用于智能提示。例如，可以使用 @type 標(biāo)簽來(lái)賦予部分聲明的 object 一個(gè)特殊類型：

/**
 * @type {{a: boolean, b: boolean, c: number}}
 */
var x = {a: true};
x.b = false;
x. // <- 由于 type 聲明，"x" 將被提示含有屬性 a,b 以及 c

JSDoc 最常見(jiàn)的使用是為函數(shù)的參數(shù)聲明類型，使用 @param 來(lái)完成：

/**
 * @param {string} param1 - 這里可以用于解釋參數(shù)含義
 */
function Foo(param1) {
 this.prop = param1; // param1 （以及 this.prop）均為 string 類型
}

為代碼添加 JSDoc 注釋使得閱讀和理解代碼更加方便（代碼交接時(shí)再也不用抓狂了，當(dāng)然前提是注釋寫得好），也保障了開(kāi)發(fā)時(shí)的體驗(yàn)并且降低了很多運(yùn)行時(shí)才能發(fā)現(xiàn)的數(shù)據(jù)類型方面的 bug。VSCode 基本支持 JSDoc 的常見(jiàn)語(yǔ)法，具體使用可參見(jiàn)JSDoc support in JavaScript。

基于 TypeScript 類型聲明文件

除了使用 JSDoc 提前聲明類型，更為激進(jìn)的做法是直接使用微軟開(kāi)發(fā)的 TypeScript，為整個(gè)項(xiàng)目帶來(lái)完善的靜態(tài)類型檢查。當(dāng)然，對(duì)于老項(xiàng)目來(lái)說(shuō)，改造的成本較為巨大（使用 Flow 也類似，要?jiǎng)拥拇a太多，況且 Flow 爛尾了）。不過(guò)由于和 TypeScript 師出同門，VSCode 能夠直接讀取前者的類型聲明文件，來(lái)為 JavaScript 提供智能提示（實(shí)際上 JavaScript 的智能提示功能就是基于 TypeScript 團(tuán)隊(duì)為 VSCode 提供的 JavaScript 語(yǔ)言服務(wù)開(kāi)發(fā)的）。 TypeScript 的類型聲明文件以 .d.ts 為后綴，用于描述同名的 JavaScript 文件導(dǎo)出代碼的類型，功能上類似于 C 語(yǔ)言的 .h 頭文件。不嚴(yán)格地來(lái)說(shuō)，ts 類型聲明文件就像用 TypeScript 語(yǔ)法將 JSDoc 的注釋重寫了一遍并提取到了單獨(dú)的文件中。VSCode 更是將二者作了融合，當(dāng)你二者混用的時(shí)候，可以直接在 JSDoc 的注釋中直接使用 ts 類型聲明文件中定義的 interface 和 class 等。直接使用官方提供的示意圖（圖中是 Visual Studio，不過(guò)無(wú)傷大雅）：

對(duì)于自己的代碼，可以編寫對(duì)應(yīng)的 ts 類型聲明文件，而對(duì)于引用的第三方庫(kù)，社區(qū)同樣提供了解決方案：DefinitelyTyped 提供了常見(jiàn)的第三方庫(kù)的類型聲明文件。VSCode 有很多第三方庫(kù)已經(jīng)內(nèi)置類型聲明文件，自己下載的話直接使用 npm 即可：

# @types + 第三方庫(kù)名稱
npm i @types/express

關(guān)于 ts 類型聲明文件的語(yǔ)法等相關(guān)信息，參見(jiàn)官網(wǎng)介紹。

另外，在 VSCode 中，類型檢查并非默認(rèn)開(kāi)啟，這意味著即使你有詳盡的 JSDoc 注釋或 ts 類型聲明文件，依然可能在數(shù)據(jù)類型上栽跟頭。開(kāi)啟方式為在項(xiàng)目根目錄下添加 jsconfig.json 文件，并設(shè)置 "checkJs": true，示例如下：

{
 "compilerOptions": {
  "checkJs": true
 },
 
 // 位于此目錄下的文件不進(jìn)行靜態(tài)檢查和智能提示
 "exclude": [
  "node_modules",
  "**/node_modules/*"
 ]
}

總結(jié)

最后，無(wú)論是對(duì)老項(xiàng)目的改造或是新項(xiàng)目的開(kāi)發(fā)，使用以上的方式添加智能提示和類型檢查顯而易見(jiàn)會(huì)略微拖慢開(kāi)發(fā)速度，但我們認(rèn)為，與智能提示帶來(lái)的開(kāi)發(fā)體驗(yàn)、將很多可能在運(yùn)行時(shí)才能發(fā)現(xiàn)的錯(cuò)誤通過(guò)類型檢查前置解決、順手完成的詳細(xì)文檔以及重構(gòu)代碼時(shí)的信心相比，這點(diǎn)速度的犧牲是值得的。

好了，以上就是這篇文章的全部?jī)?nèi)容了，希望本文的內(nèi)容對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，謝謝大家對(duì)億速云的支持。

參考文檔：

• JavaScript in Visual Studio Code
• Working with JavaScript
• JavaScript Language Service in Visual Studio