前言

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

基于 JSDoc

JSDoc 是目前最通用的 JavaScript API 文檔生成器，根據其語法編寫代碼注釋，可以十分方便地自動生成文檔。由于 JSDoc 能提供詳細的類型信息，其也被 VSCode 等編輯器接受應用于智能提示。例如，可以使用 @type 標簽來賦予部分聲明的 object 一個特殊類型：

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

JSDoc 最常見的使用是為函數的參數聲明類型，使用 @param 來完成：

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

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

基于 TypeScript 類型聲明文件

除了使用 JSDoc 提前聲明類型，更為激進的做法是直接使用微軟開發的 TypeScript，為整個項目帶來完善的靜態類型檢查。當然，對于老項目來說，改造的成本較為巨大（使用 Flow 也類似，要動的代碼太多，況且 Flow 爛尾了）。不過由于和 TypeScript 師出同門，VSCode 能夠直接讀取前者的類型聲明文件，來為 JavaScript 提供智能提示（實際上 JavaScript 的智能提示功能就是基于 TypeScript 團隊為 VSCode 提供的 JavaScript 語言服務開發的）。 TypeScript 的類型聲明文件以 .d.ts 為后綴，用于描述同名的 JavaScript 文件導出代碼的類型，功能上類似于 C 語言的 .h 頭文件。不嚴格地來說，ts 類型聲明文件就像用 TypeScript 語法將 JSDoc 的注釋重寫了一遍并提取到了單獨的文件中。VSCode 更是將二者作了融合，當你二者混用的時候，可以直接在 JSDoc 的注釋中直接使用 ts 類型聲明文件中定義的 interface 和 class 等。直接使用官方提供的示意圖（圖中是 Visual Studio，不過無傷大雅）：