為什么用 TypeScript？

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

1.第一時(shí)間發(fā)現(xiàn)類型錯(cuò)誤

據(jù) rollbar 統(tǒng)計(jì)，在前端項(xiàng)目中 10 大錯(cuò)誤類型如下圖所示：

其中有 7 個(gè)是類型錯(cuò)誤（TypeError）：

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

除了 7 個(gè) TypeError，還有一個(gè) ReferenceError：

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

還有一個(gè) RangeError：

• 在 JS 中，數(shù)組越界并不會(huì)拋出 RangeError，但是某些函數(shù)則拋出這個(gè)錯(cuò)誤

嘿嘿，看著這些錯(cuò)誤眼不眼熟？

由于 JavaScript 是一門很靈活的語言，所以以上這些錯(cuò)誤往往要在代碼運(yùn)行時(shí)才能發(fā)現(xiàn)。

2.智能提示

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

但是基于 TypeScript，由于知道當(dāng)前變量是什么類型，所以編輯器能經(jīng)過類型推導(dǎo)后為你提示這個(gè)變量的所有屬性，以及對于函數(shù)的參數(shù)進(jìn)行提示和校驗(yàn)。

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

至于其他的優(yōu)點(diǎn)在這里就不展開了...

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

TypeScript 初體驗(yàn)

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

語言學(xué)習(xí)

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

項(xiàng)目架構(gòu)

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

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

相關(guān)工具鏈

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

• 1.代碼轉(zhuǎn)譯 babel（[譯] TypeScript 和 Babel：美麗的結(jié)合）

TypeScript 和 babel 都可以將你的 ES6+ 代碼轉(zhuǎn)成 ES5。

但在 Babel v7 之前將兩個(gè)獨(dú)立的編譯器（TypeScript 和 Babel）鏈接在一起并非易事。編譯流程變?yōu)?#xff1a;TS > TS Compiler > JS > Babel > JS (again)。

現(xiàn)在只要安裝 @babel/preset-typescript 這個(gè)包就能讓你完美結(jié)合 babel 和 TypeScript。

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

再也不用糾結(jié)到底用 tslint 還是 eslint 了，TypeScript 官方已經(jīng)欽定了 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 轉(zhuǎn)投 TypeScript 的懷抱了

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

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

改造過程

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

文檔

文檔標(biāo)準(zhǔn)

TypeScript 官方有一套基于 jsdoc 的文檔標(biāo)準(zhǔn) 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 這個(gè)自動(dòng)文檔網(wǎng)站生成器。但這玩意兒的常規(guī)操作就是讀取源代碼，然后 duang 地一下，生成一堆頁面。

雖然這樣解決了文檔生成，但是沒法進(jìn)行開發(fā)時(shí)實(shí)時(shí)預(yù)覽文檔。

自動(dòng)生成

0.失敗嘗試：結(jié)合 vuepress

由于 typedoc 能導(dǎo)出 md 文件，所以嘗試過將其結(jié)合 vuepress。不過由于 typedoc 在生成時(shí)會(huì)先清空目標(biāo)目錄下所有文件，折騰起來太麻煩（比如做個(gè)插件）。

1.下策：手動(dòng)觸發(fā)文檔生成

沒啥好說的，適用于有毅力的同學(xué)。

2.中策：監(jiān)聽源文件變化，自動(dòng)觸發(fā)文檔生成

雖然能自動(dòng)生成文檔頁面了，不過預(yù)覽時(shí)沒法自動(dòng)刷新頁面。

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

說到開發(fā)時(shí)自動(dòng)刷新頁面，第一個(gè)自然想到 browser-sync。

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

最后這里貼一下 gulpfile.js 的代碼，節(jié)省一下也有相關(guān)需求同學(xué)的時(shí)間吧。

const gulp = require('gulp') const typedoc = require('gulp-typedoc') const browserSync = require('browser-sync').create()const runTypeDoc = () => gulp.src(['src']).pipe(typedoc({out: './docs',// 這個(gè)文件里都是 export * from '...' 就沒必要導(dǎo)出文檔了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 官網(wǎng)
• TypeScript 解決了什么痛點(diǎn)？ - justjavac的回答 - 知乎
• @babel/preset-typescript
• [譯] TypeScript 和 Babel：美麗的結(jié)合
• 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

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。