嘗試造了個工具類庫,名為 Diana
項目地址: diana
文檔地址: http://muyunyun.cn/diana/
造輪子的意義
為啥已經有如此多的前端工具類庫還要自己造輪子呢?個人認為有以下幾個觀點吧:
- 定制性強,能根據自己的需求為主導延伸開發。萬一一不小心還能幫到別人(比如 React 庫);
- 紙上得來終覺淺,很多流行的庫,只是照著它們的 API 進行使用,其實這些庫裏蘊含著大量的知識、技巧,最好的辦法就是仿照它們來寫些小 demo,從而體會這些庫的精髓;
- 造輪子的過程中能讓自己體會到與平常業務開發不一樣的樂趣;比如和日常業務開發中很大的一個區別是會對測試用例具有比較嚴格的要求;而且寫文檔能力提升了。
- 就先瞎編到這裏了。。。
拋開內部方法(寫相應的專題效果可能會更好,所以這裏先略過),下面分享一些開發 diana 庫 時的一些心得:
項目目錄結構
├── LICENSE 開源協議 ├── README-zh_en.md 英文說明文檔 ├── README.md 中文說明文檔 ├── coverage 代碼覆蓋率文件 ├── docs 文檔目錄 │?? └── static-parts │?? ├── index-end.html 靜態文檔目錄結尾文件 │?? └── index-start.html 靜態文檔目錄開頭文件 ├── karma.conf.js karma 配置文件 ├── lib │?? ├── diana.back.js 服務端引用入口 │?? └── diana.js 瀏覽器引用入口 ├── package.json ├── script │?? ├── build.js 構建文件 │?? ├── check.js 結合 pre-commit 進行 eslint 校驗 │?? ├── tag-script.js 自動生成文檔的標簽 │?? ├── web-script.js 自動生成文檔 │?? ├── webpack.browser.js 瀏覽器端 webpack 配置文件 │?? └── webpack.node.js 服務器端 webpack 配置文件 ├── snippets ├── src │?? ├── browser 瀏覽器端方法 │?? ├── common 共用方法 │?? ├── node node 端方法 │?? └── util.js 庫內通用方法 ├── tag_database 文檔標簽 └── test 測試文件 ├── browserTest ├── commonTest ├── index.js └── nodeTest
目錄結構也隨著方法的增多在不停叠代當中,建議直接到庫中查看最新的目錄結構。
相應地,具體的方法會隨著時間叠代,所以首先推薦查看文檔,點擊如下圖的 ? 就能查看源碼。
讓模塊同時在 Node.js 與瀏覽器中運行
我們可以通過如下方法來判斷模塊當前是運行在 Node.js 還是瀏覽器中,然後使用不同的方式實現我們的功能。
// Only Node.JS has a process variable that is of [[Class]] process
const isNode = Object.prototype.toString.call(typeof process !== 'undefined' ? process : 0) === '[object process]'
但如果用戶使用了模塊打包工具,這樣做會導致 Node.js 與瀏覽器的實現方式都會被包含在最終的輸出文件中。針對這個問題,開源社區提出了在 package.json 中添加 browser 字段的提議,目前 webpack 和 rollup 都已經支持這個字段了。
給 browser 字段提供一個文件路徑作為在瀏覽器端使用時的模塊入口,但需要註意的是,打包工具會優先使用 browser 字段指定的文件路徑作為模塊入口,所以你的 main 字段 和 module 字段會被忽略,但是這會導致打包工具不會優化你的代碼。詳細信息請參考這個問題。
在 diana 庫 為了在不同環境中使用適當的文件,在 package.json 中進行了如下聲明:
"browser": "lib/diana.js",
"main": "lib/diana.back.js", // 或者 "module": "lib/diana.back.js",
這樣一來,在 node 環境中,引用的是 lib/diana.back.js
文件,在瀏覽器環境中,引用的是 lib/diana.js
文件。然後就能愉快地在瀏覽器端和 node 端愉快地使用自己特有的 api 了。
常見模塊規範比較
另外為了使 diana 庫 的打包文件兼容 node 端、以及瀏覽器端的引用,選擇了 UMD 規範進行打包,那麽為什麽要選擇 UMD 規範呢?讓我們看下以下幾種規範之間的異同:
CommonJS
CommonJs 是服務器端模塊的規範,
Node.js 采用了這個規範
。這些規範涵蓋了模塊、二進制、Buffer、字符集編碼、I/O流、進程環境、文件系統、套接字、單元測試、服務器網關接口、包管理等。根據 CommonJS 規範,一個單獨的文件就是一個模塊。加載模塊使用
require
方法,該方法讀取一個文件並執行,最後返回文件內部的exports
對象。CommonJS 加載模塊是同步的。像 Node.js 主要用於服務器的編程,加載的模塊文件一般都已經存在本地硬盤,所以加載起來比較快,不用考慮異步加載的方式,所以 CommonJS 規範比較適用。但如果是瀏覽器環境,要從服務器加載模塊,這是就必須采用異步模式。所以就有了 AMD、CMD 解決方案。
AMD、CMD
AMD 是 RequireJS 在推廣過程中對模塊定義的規範化產物。AMD 推崇提前執行。
// AMD 默認推薦的是 define(['./a', './b'], function(a, b) { a.doSomething() b.doSomething() ... })
CMD 是 SeaJS 在推廣過程中對模塊定義的規範化產物。CMD 推崇依賴就近。
// CMD define(function(require, exports, module) { var a = require('./a') a.doSomething() var b = require('./b') b.doSomething() ... })
UMD
UMD 是 AMD 和 CommonJS 的結合。因為 AMD 是以瀏覽器為出發點的異步加載模塊,CommonJS 是以服務器為出發點的同步加載模塊,所以人們想出了另一個更通用的模式 UMD,來解決跨平臺的問題。
diana 庫 選擇了以 umd 方式進行輸出,來看下 UMD 做了啥:
(function (root, factory) {
if (typeof exports === 'object' && typeof module === 'object') { // UMD 先判斷是否支持 Node.js 的模塊(exports)是否存在,存在則使用 CommonJS 模式
module.exports = factory()
} else if (typeof define === 'function' && define.amd) { // 接著判斷是否支持 AMD(define是否存在),存在則使用 AMD 方式加載模塊。
define([], factory)
} else if (typeof exports === 'object') { // CommonJS 的另一種形式
exports['diana'] = factory()
} else
root['diana'] = factory() // Window
})(this, function() {
return module
})
測試踩坑之路
代碼覆蓋率
單元測試的代碼覆蓋率統計,是衡量測試用例好壞的一個的方法。但凡是線上用的庫,基本上都少不了高質量的代碼覆蓋率的檢測。如下圖為 diana 庫的測試覆蓋率展示。
可以看到覆蓋率分為以下 4 種類型,
- 行覆蓋率(line coverage):是否每一行都執行了?
- 函數覆蓋率(function coverage):是否每個函數都調用了?
- 分支覆蓋率(branch coverage):是否每個if代碼塊都執行了?
- 語句覆蓋率(statement coverage):是否每個語句都執行了?
番外:github 上顯示的覆蓋率是根據行覆蓋率來展示的。
mocha + istanbul
最初的版本, 僅僅用到 mocha 進行測試 *.test.js 文件,然後在 codecov 得到測試覆蓋率。
引人 karma
如果僅僅測試 es5、es6 的語法,其實用 mocha 就已經夠用了,但是涉及到測試 Dom 操作的語法等就必須建立一個瀏覽器,在上面進行測試。karma 的作用其實就是自動幫我們建立一個測試用的瀏覽器環境。
為了讓瀏覽器支持 Common.js 規範,中間用了 karma + browserify,盡管測試用例都跑通了,但是最後的代碼覆蓋率的文件裏只有各個方法的引用路徑。最後只能又回到 karma + webpack 來,這裏又踩到一個坑,打包編譯JS代碼覆蓋率問題,踩了一些坑後,終於實現了可以查看編譯前代碼的覆蓋率。圖如下:
通過這幅圖我們能清晰地看到源代碼中測試用例跑過各行代碼的次數(左側的數字),以及測試用例沒有覆蓋到的代碼(圖中紅色所示)。然後我們就能改善相應的測試用例從而提高測試覆蓋率。
配置文件,核心部分如下:
module.exports = function(config) {
config.set({
files: ['test/index.js'], // 需載入瀏覽器的文件
preprocessors: { // 預處理
'test/index.js': ['webpack', 'coverage']
},
webpack: {
module: {
rules: [{
test: /\.js$/,
use: { loader: 'sourcemap-istanbul-instrumenter-loader' }, // 這裏用 istanbul-instrumenter-loader 插件的 0.0.2 版本,其它版本有坑~
exclude: [/node_modules/, /\.spec.js$/],
}],
}
},
coverageReporter: {
type: 'lcov', // 貌似只能支持這種類型的讀取
dir: 'coverage/'
},
remapIstanbulReporter: { // 生成 coverage 文件
reports: {
'text-summary': null,
json: 'coverage/coverage.json',
lcovonly: 'coverage/lcov.info',
html: 'coverage/html/',
}
},
reporters: ['progress', 'karma-remap-istanbul'], // remap-isbanbul 也報了一個未找到 sourcemap 的 error,直接註釋了 remap-istanbul 包的 CoverageTransformer.js 文件的 169 行,以後有機會再搗鼓吧。(心累)
...
})
}
總結
本文圍繞 diana 庫 對造輪子的意義,模塊兼容性,測試用例進行了思考總結。後續會對該庫流程自動化以及性能上做些分享。
該庫參考學習了很多優秀的庫,感謝 underscore、outils、ec-do、30-seconds-of-code 等庫對我的幫助。
最後歡迎各位大佬在 issues 盡情吐槽。
嘗試造了個工具類庫,名為 Diana