最近在做公司內(nèi)部的一個(gè)的一個(gè)SDK的重構(gòu)，這里總結(jié)一些經(jīng)驗(yàn)分享給大家。
類型檢查和智能提示
作為一個(gè)SDK，我們的目標(biāo)是讓使用者能夠減少查看文檔的時(shí)間，所以我們需要提供一些類型的檢查和智能提示，一般我們的做法是提供JsDoc，大部分編輯器可以提供快捷生成JsDoc的方式，我們比較常用的vscode可以使用Document
This（https://marketplace.visualstudio.com/items?itemName=joelday.docthis）。
另一種做法是使用Flow或者TypeScript，選擇TypeScript的主要原因是自動生成的JsDoc比較原始，我們?nèi)匀恍枰谏厦孢M(jìn)行編輯，所以JsDoc維護(hù)和代碼開發(fā)是脫離的，往往會出現(xiàn)代碼更新了，JsDoc忘記更新的情況。
除此之外開發(fā)過程中我們無法享受到類型檢查等對SDK開發(fā)比較重要的特性，TypeScript可以讓我們減少犯錯(cuò)，減少調(diào)試的時(shí)間，另一方面這次開發(fā)的SDK在提供出去的時(shí)候就會進(jìn)行一次相對簡單的壓縮，保證引入后的體積，所以會希望壓縮掉JsDoc，而TypeScript可以通過在tsconfig.json中將declaration設(shè)置為true單獨(dú)的d.ts文件。
一個(gè)帶提示的SDK：
最后,對于開發(fā)同學(xué)來說，就算不使用TypeScript，也強(qiáng)烈建議使用vscode提供//@ts-check?注解，它會通過一些類型推導(dǎo)來檢查你的代碼的正確性，可以減少很多開發(fā)過程中的bug。
還有一個(gè)小技巧，如果你使用的庫沒有提供智能提示，你可以通過NPM/yarn的-D安裝@types/{pkgname}，這樣你開發(fā)過程中就能夠享受到vscode提供的智能提示，而-D安裝到devDependencies中，也不會增加你在構(gòu)建時(shí)的代碼體積。
接口
既然提到了TypeScript，就提一下TypeScript的語法，基礎(chǔ)類型沒有必要贅述，而一些曾經(jīng)的高級語法現(xiàn)在ES6也都能支持，這里提幾點(diǎn)常用但是JavaScript開發(fā)者不太習(xí)慣使用的語法。
很多人在開始使用TypeScript的時(shí)候，會很迷戀使用any或者默認(rèn)的any，推薦在開發(fā)中打開tsconfig中的strict和noImplicitAny來保證盡量少的any使用，要知道，濫用any就等于你的類型檢查并沒有實(shí)質(zhì)效果。
對一些暫時(shí)不能確定內(nèi)容的對象的類型,可以使用{[key: string]: any}，而不要直接使用any，后期可以慢慢擴(kuò)展這個(gè)接口直到完全消除any，同時(shí)TypeScript的類型支持繼承，在開發(fā)過程中，可以拆解接口，利用組合繼承的方式減少重復(fù)定義。
但是接口也會帶來一個(gè)小痛點(diǎn)，目前vscode的智能提醒不能很好的對應(yīng)到接口，當(dāng)你輸入到對應(yīng)變量的時(shí)候，雖然會高亮，但是高亮的也只是一個(gè)定義了名字的接口。沒有辦法直接看到接口里定義了什么。但是當(dāng)你輸入了接口里面定義的key的部分時(shí)，vscode會給你完整key的提示。雖然這對開發(fā)過程中有一點(diǎn)不夠友好，但是vscode開發(fā)團(tuán)隊(duì)表示這是他們故意設(shè)計(jì)的，所以在API參數(shù)上可以選擇將一些必要（重要）參數(shù)用基礎(chǔ)類型直接使用，而將一些配置放入一個(gè)定義為接口的對象中。
枚舉
你有在代碼中使用過：
const?Platform?=?{
????ios:?0,
??????android:?1
}
那你在TypeScript中就應(yīng)該使用枚舉：
enum?Platform?{
??ios,
??android
}
這樣在函數(shù)中你就可以為某個(gè)參數(shù)設(shè)置類型為number，然后傳入Platform.ios這樣，枚舉可以增加代碼的維護(hù)性，它可以利用智能提示保證你輸入的正確，不再會出現(xiàn)魔數(shù)（magic
number）。相對于對象，它保證了輸入的類型（你定義的對象可能某一天不再只有number類型的value），不再需要額外的類型判斷。
裝飾器
對于裝飾器其實(shí)很多開發(fā)者既熟悉又陌生,在redux,mobx比較流行的現(xiàn)在,在代碼中出現(xiàn)裝飾器的調(diào)用已經(jīng)很普遍,但是大多數(shù)開發(fā)者并沒有將自己代碼邏輯抽成裝飾器的習(xí)慣。
比如在這個(gè)SDK的開發(fā)中,我們需要提供一些facade來兼容不同的平臺(iOS,
Android或者Web)，而這個(gè)facade會通過插件的形式讓開發(fā)者自己注冊，SDK會維護(hù)一個(gè)注入后的對象，常規(guī)的使用方法是到了使用函數(shù)后判斷環(huán)境再判斷對象中有沒有想有的插件，有就使用插件。
實(shí)際來看，插件就是一個(gè)攔截器，我們只要阻止真正的函數(shù)運(yùn)行就可以，大概的邏輯是這樣的：
export?function?facade(env:?number)?{
??return?function(
????target:?object,
????name:?string,
????descriptor:?TypedPropertyDescriptor
??)?{
????let?originalMethod?=?descriptor.value;
????let?method;
????return?{
??????...descriptor,
??????value(...args:?any[]):?any?{
????????let?[arg]?=?args;
????????let?{?param,?success,?failure,?polyfill?}?=?arg;???// 這部分可以自定義
????????if?((method?=?polyfill[env]))?{
??????????method.use(param,?success,?failure);
??????????return;
????????}
????????originalMethod.apply(this,?args);
??????}
????};
??};
}
在SDK的開發(fā)過程中另一個(gè)常會遇到的就是很多參數(shù)的校驗(yàn)和再封裝，我們也可以使用裝飾器去完成：
export?function?snakeParam(
??target:?object,
??name:?string,
??descriptor:?TypedPropertyDescriptor
)?{
??let?callback?=?descriptor.value!;
??return?{
????...descriptor,
????value(...args:?any[]):?any?{
??????let?[arg,?...other]?=?args;
??????arg?=?convertObjectName(arg,?ConvertNameMode.toSnake);
??????callback.apply(this,?[arg,?...other]);
????}
??};
}
泛形
泛形可以根據(jù)用戶的輸入決定輸出，最簡單的例子是
function?identity(arg:?T):?T?{
????return?arg;
}
當(dāng)然它沒有什么特別的意義，但是它表明了返回是根據(jù)arg的類型，在一般開發(fā)過程中，你逃不開范型的是Promise或者前面的TypedPropertyDescriptor這種內(nèi)建的需要類型輸入的地方，不要草率的使用any，如果你的后端返回是一個(gè)標(biāo)準(zhǔn)結(jié)構(gòu)體類似：
export?interface?IRes?{
??status:?number;
??message:?string;
??data?:?object;
}
那么你可以這樣使用Promise：
function?example():?Promise?{
????return?new?Promise?...
}
當(dāng)然泛形有很多高級應(yīng)用，例如泛形約束，泛型創(chuàng)建工廠函數(shù)，已經(jīng)超出了本文的范圍，可以去官方文檔了解。
構(gòu)建
如果你的構(gòu)建工具是Webpack，在SDK的開發(fā)中，盡量使用node方式調(diào)用（即webpack.run執(zhí)行），因?yàn)镾DK的構(gòu)建往往會應(yīng)對很多不同的參數(shù)變化，node方式相比純配置方式可以更加靈活的調(diào)整輸入輸出的參數(shù)，也可以考慮使用rollup，rollup的構(gòu)建代碼更加面向編程方式。
需要注意的是，在Webpack3和rollup中構(gòu)建中可以使用ES6模塊化的方式構(gòu)建，這樣業(yè)務(wù)代碼引入你的SDK后，可以通過解構(gòu)引入的方式減少最終業(yè)務(wù)代碼的體積，如果你只是提供了commonjs的包，那么構(gòu)建工具的tree
sharking是無法生效的，如果使用babel的話注意關(guān)閉module的編譯。
另外一種減少單個(gè)包體積的方式，可以使用lerna在一個(gè)git倉庫里構(gòu)建多個(gè)NPM包，比起拆倉庫可以更方便的使用公共部分的代碼，但是也需要注意對公共部分代碼的修改不要影響到別的包。
其實(shí)對于大多數(shù)的SDK的來說，Webpack3和rollup使用感受是差不多的，比較常用的插件都有幾乎同名的對應(yīng)。不過rollup有兩個(gè)優(yōu)勢，一個(gè)是rollup的構(gòu)建更細(xì)化，rollup.rollup接受inputOptions生成bundle，還可以generate生成sourcemap，write生成output，在這個(gè)過程中我們可以做一些細(xì)致的工作。
第二點(diǎn)是rollup.rollup會返回一個(gè)promise，也就意味著我們可以使用async的方式來寫構(gòu)建代碼，而webpack.run還是使用的回調(diào)函數(shù)，雖然開發(fā)者可以封裝成promise，但是個(gè)人覺得還是rollup的寫法還是更爽一點(diǎn)。
單元測試
上周我同事做了一個(gè)在線的分享，我發(fā)現(xiàn)很多同學(xué)都對單測很感興趣也很疑惑，在前端開發(fā)中，對涉及UI的業(yè)務(wù)代碼開發(fā)單測試比較困難的，但是對于SDK，單元測試肯定是準(zhǔn)出的一個(gè)充要條件。當(dāng)然其實(shí)我也很不喜歡寫單測，因?yàn)閱螠y往往比較枯燥，但是不寫單測肯定會被老司機(jī)們“教育”的。
一般的單測使用mocha作為測試框架，expect作為斷言庫，使用nyc提供單測報(bào)告，一個(gè)大概的單測如下：
describe('xxx api test',?function()?{????????????// 注意如果要用this調(diào)用mocha，不要用箭頭函數(shù)
??this.timeout(6000);
??it('xxx',?done?=>?{
????SDK.file
??????.chooseImage({
????????count:?10,
????????cancel:?()?=>?{
??????????console.log('選擇圖片取消----');
????????}
??????})
??????.then(res?=>?{
????????console.dir(res);
????????expect(res).to.be.an('object');
????????expect(res).to.have.keys('ids');
????????expect(res.ids).to.be.an('array');
????????expect(res.ids).to.have.length.above(0);
????????uploadImg(res.ids);
????????done();
??????});
??});
});
同樣你可以用TypeScript寫單測，當(dāng)然在執(zhí)行過程中，不需要再編譯了，我們可以直接給mocha注冊ts-node來直接執(zhí)行，具體方式可以參考Write
tests for TypeScript projects with mocha and chai?—?in
TypeScript!。但是有一點(diǎn)需要提醒你，寫單測的時(shí)候盡量依賴文檔而不是智能提示，因?yàn)槟愕拇a出錯(cuò)，可能會導(dǎo)致你的智能提示也是錯(cuò)誤的，你根據(jù)錯(cuò)誤的智能提示寫的單測肯定也是。
對于網(wǎng)絡(luò)請求的模擬可以使用nock這個(gè)庫，需要在it之前增加一個(gè)beforeEach方法：
describe('proxy',?()?=>?{
??beforeEach(()?=>?{
????nock('http://test.com')
??????.post('/test1')
??????.delay(200)
??????.reply(200,?{????????????// body
????????test1:?1,
????????test2:?2
??????},?{
????????'server-id':?'test'?// header
??????});
??});
??it(...
}
最后我們用一個(gè)npm script加上nyc在mocha前面，就可以獲得我們的單測報(bào)告了。
這里我還提了幾個(gè)TypeScript使用中的小tips給大家參考。
tips: 如何在非發(fā)包情況下給內(nèi)部庫添加聲明
這個(gè)SDK在開發(fā)過程會依賴一個(gè)內(nèi)部NPM包,為了讓這個(gè)NPM支持TypeScript調(diào)用,我們有幾種做法：
給原包添加d.ts文件，然后發(fā)布。
發(fā)布@types包，需要注意的是NPM不支持@types/@scope/{pkgname}這種寫如果是私庫包，可以使用@types/scope_{pkgname}這種寫法。
這次使用的標(biāo)注一個(gè)文件夾存放對應(yīng)的d.ts文件，這種方式適合開發(fā)中進(jìn)行，如果你覺得你寫的d.ts還不夠完美，或者這個(gè)d.ts文件目前只有這個(gè)SDK有需要，可以這么使用，在tsconfig.json中修改:
"baseUrl":?"./",
"paths":?{
????"*":?["/type/*"]
}
tips: 如何處理resolve和reject不同類型的promise回調(diào)
默認(rèn)的reject返回的參數(shù)類型是any，不一定能滿足我們的需要，這里給一個(gè)解決方案，并非最佳，作為拋磚引玉：
interface?IPromise?{
??then(
????onfulfilled?:
??????|?((value:?T)?=>?TResult1?|?PromiseLike)
??????|?undefined
??????|?null,
????onrejected?:
??????|?((reason:?U)?=>?TResult2?|?PromiseLike)
??????|?undefined
??????|?null
??):?IPromise;
??catch(
????onrejected?:
??????|?((reason:?U)?=>?TResult?|?PromiseLike)
??????|?undefined
??????|?null
??):?Promise;
編輯：千鋒HTML5
本文作者：陳達(dá)孚
香港中文大學(xué)研究生，《移動Web前端高效開發(fā)實(shí)戰(zhàn)》作者之一，《前端開發(fā)者指南2017》譯者之一，在中國前端開發(fā)者大會,中生代技術(shù)大會等技術(shù)會議發(fā)表過主題演講， 專注于新技術(shù)的調(diào)研和使用。
