為什么用 TypeScript？

TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Any browser. Any host. Any OS. Open source. ———— TypeScript 官網

1.第一時間發現類型錯誤

據 rollbar 統計，在前端項目中 10 大錯誤類型如下圖所示：

其中有 7 個是類型錯誤（TypeError）：

• Cannot read property 'xxx' on undefined：無法在 undefined 上讀取 xxx 屬性，通常出現在 a.b.c 的情況。
• 'undefined' is not an object：undefined 不是對象
• null is not an object：null 不是對象
• 'undefined' is not a function：undefined 不是函數，通常出現在 a.b.c() 的情況。
• Object doesn't support property
• Cannot read property 'length'：無法讀取 'length' 屬性，本來期望一個數組，但是變量的實際類型卻不是數組。
• Cannot set property of undefined：無法給 undefined 設置屬性。

除了 7 個 TypeError，還有一個 ReferenceError：

• 'xxx' is not defined：xxx 沒有定義。

還有一個 RangeError：

• 在 JS 中，數組越界并不會拋出 RangeError，但是某些函數則拋出這個錯誤

嘿嘿，看著這些錯誤眼不眼熟？

由于 JavaScript 是一門很靈活的語言，所以以上這些錯誤往往要在代碼運行時才能發現。

2.智能提示

在使用 JavaScript 時，編輯器的智能提示往往很有限，比如提示你最近輸入的變量。

但是基于 TypeScript，由于知道當前變量是什么類型，所以編輯器能經過類型推導后為你提示這個變量的所有屬性，以及對于函數的參數進行提示和校驗。

此外，對于一般的 JavaScript 項目也可以自己編寫 .d.ts 聲明文件，來獲取類型推導能力。

至于其他的優點在這里就不展開了...

綜上，在項目中使用 TypeScript 能讓你極大地提高工作效率，并減少大量的類型錯誤。

TypeScript 初體驗

由于目前業務項目中的框架用的是 Vue.js，眾所周知 2.x 版本對于 TypeScript 支持的不是很好，所以就打算先搞個工具函數庫項目試試水。

語言學習

略，這個各種資料很多，這里就不贅述了...

項目架構

• 項目入口：src/index.ts，沒有實質內容全是 export * from '...'（都是純函數）
• 實際代碼：根據工具函數分類放在不同的文件中，例如
• string（字符串相關）
• env（環境探測）
• url（鏈接地址）
• ...
• 單元測試：test/
• 文檔目錄：docs/

注意：package.json 中的 sideEffects 字段要寫成 false，這樣可以方便業務代碼打包時 tree-shaking。

相關工具鏈

之前對于 TypeScript 一直在觀望的原因之一就是相關工具鏈的搭配還不是很成熟。不過現在倒是基本明晰了：

• 1.代碼轉譯 babel（[譯] TypeScript 和 Babel：美麗的結合）

TypeScript 和 babel 都可以將你的 ES6+ 代碼轉成 ES5。

但在 Babel v7 之前將兩個獨立的編譯器（TypeScript 和 Babel）鏈接在一起并非易事。編譯流程變為：TS > TS Compiler > JS > Babel > JS (again)。

現在只要安裝 @babel/preset-typescript 這個包就能讓你完美結合 babel 和 TypeScript。

• 2.代碼檢查 eslint（The future of TypeScript on ESLint）

再也不用糾結到底用 tslint 還是 eslint 了，TypeScript 官方已經欽定了 eslint（Migrate the repo to ESLint #30553）。

• 3.單元測試 jest（[RFC] Migrate Jest to TypeScript #7554）

嘿嘿，Facebook 的 jest 和 yarn（Yarn's Future - v2 and beyond #6953） 都拋棄自家的 Flow 轉投 TypeScript 的懷抱了

• 4.代碼打包 rollup（rollup 在 17 年底就使用 TypeScript 重寫了）

雖然 rollup 自己用的是 rollup-plugin-typescript，不過項目中還是選了 rollup-plugin-typescript2。

改造過程

• 安裝各種依賴
• 配好各種配置文件（eslint、babel、commitlint、jest），其中最重要的是 tsconfig.json
• 源代碼的文件名后綴由 .js 改成 .ts（單測的文件也改）
• 然后 TypeScript 的靜態代碼類型檢查就會告訴你有什么錯誤
• 看情況改代碼，或者是加 ignore 注釋（有時甚至需要改 tsconfig 的配置）

文檔

文檔標準

TypeScript 官方有一套基于 jsdoc 的文檔標準 tsdoc。

export class Statistics {/*** Returns the average of two numbers.** @remarks* This method is part of the {@link core-library#Statistics | Statistics subsystem}.** @param x - The first input number* @param y - The second input number* @returns The arithmetic mean of `x` and `y`** @beta*/public static getAverage(x: number, y: number): number {return (x + y) / 2.0;} }

生成文檔

于是順藤摸瓜找到 typedoc 這個自動文檔網站生成器。但這玩意兒的常規操作就是讀取源代碼，然后 duang 地一下，生成一堆頁面。

雖然這樣解決了文檔生成，但是沒法進行開發時實時預覽文檔。

自動生成

0.失敗嘗試：結合 vuepress

由于 typedoc 能導出 md 文件，所以嘗試過將其結合 vuepress。不過由于 typedoc 在生成時會先清空目標目錄下所有文件，折騰起來太麻煩（比如做個插件）。

1.下策：手動觸發文檔生成

沒啥好說的，適用于有毅力的同學。

2.中策：監聽源文件變化，自動觸發文檔生成

雖然能自動生成文檔頁面了，不過預覽時沒法自動刷新頁面。

3.上策：借助 webpack、gulp、grunt 自動生成文檔并刷新頁面（正好有這三者的 typedoc 插件）

說到開發時自動刷新頁面，第一個自然想到 browser-sync。

• 雖說 webpack 無所不能，不過殺雞焉用牛刀
• grunt 這玩意兒有點兒落伍了
• gulp 正好以前搗鼓過，加這個小需求正好

最后這里貼一下 gulpfile.js 的代碼，節省一下也有相關需求同學的時間吧。

const gulp = require('gulp') const typedoc = require('gulp-typedoc') const browserSync = require('browser-sync').create()const runTypeDoc = () => gulp.src(['src']).pipe(typedoc({out: './docs',// 這個文件里都是 export * from '...' 就沒必要導出文檔了exclude: 'src/index.ts',tsconfig: 'tsconfig.json',}))const reload = (done) => {browserSync.reload()done() }const runBrowserSync = (done) => {browserSync.init({server: {baseDir: './docs',},})done() }const watch = () => gulp.watch(['README.md', 'src/*.ts'],gulp.series(runTypeDoc, reload) )gulp.task('default', gulp.series(runTypeDoc, runBrowserSync, watch))

以上 to be continued...

參考資料

• TypeScript 官網
• TypeScript 解決了什么痛點？ - justjavac的回答 - 知乎
• @babel/preset-typescript
• [譯] TypeScript 和 Babel：美麗的結合
• The future of TypeScript on ESLint
• Migrate the repo to ESLint #30553
• [RFC] Migrate Jest to TypeScript #7554
• Yarn's Future - v2 and beyond #6953
• rollup 在 17 年底就使用 TypeScript 重寫了
• rollup-plugin-typescript2
• tsdoc
• typedoc
• browser-sync
• typedoc 插件
• rollbar

總結

以上是生活随笔為你收集整理的docwizard c++程序文档自动生成工具_如何开发一个基于 TypeScript 的工具库并自动生成文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。