爲你的 JavaScript 項目添加智能提示和類型檢查

本文首發於個人博客（點此查看），歡迎關注。

前言

最近在作項目代碼重構，其中有一個要求是爲代碼添加智能提示和類型檢查。智能提示，英文爲 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，不過無傷大雅）：

對於本身的代碼，能夠編寫對應的 ts 類型聲明文件，而對於引用的第三方庫，社區一樣提供瞭解決方案：DefinitelyTyped 提供了常見的第三方庫的類型聲明文件。VSCode 有不少第三方庫已經內置類型聲明文件，本身下載的話直接使用 npm 便可：

# @types + 第三方庫名稱
npm i @types/express
複製代碼

關於 ts 類型聲明文件的語法等相關信息，參見官網介紹。

另外，在 VSCode 中，類型檢查並不是默認開啓，這意味着即便你有詳盡的 JSDoc 註釋或 ts 類型聲明文件，依然可能在數據類型上栽跟頭。開啓方式爲在項目根目錄下添加 jsconfig.json 文件，並設置 "checkJs": true，示例以下：

{
    "compilerOptions": {
        "checkJs": true
    },
    
    // 位於此目錄下的文件不進行靜態檢查和智能提示
    "exclude": [
        "node_modules",
        "**/node_modules/*"
    ]
}
複製代碼

總結

最後，不管是對老項目的改造或是新項目的開發，使用以上的方式添加智能提示和類型檢查顯而易見會略微拖慢開發速度，但咱們認爲，與智能提示帶來的開發體驗、將不少可能在運行時才能發現的錯誤經過類型檢查前置解決、順手完成的詳細文檔以及重構代碼時的信心相比，這點速度的犧牲是值得的。

參考文檔：

JavaScript in Visual Studio Code

Working with JavaScript

JavaScript Language Service in Visual Studio