Whats API?

　　API的全稱是application programming interface。

　　而很多時(shí)候，程序開發(fā)者僅僅把函數(shù)、類的接口做為API的一部分，而忽略了其他重要的編程接口。

　　事實(shí)上，在前端Javscript編程中常見的API包括：

• 函數(shù)、類接口，包括參數(shù)，返回值，函數(shù)對(duì)外部對(duì)象（常常是DOM）的具體操作等
• 網(wǎng)絡(luò)接口協(xié)議，如和后端交互的JSON、XML數(shù)據(jù)格式，或者script回調(diào)中的函數(shù)名
• 樣式以及HTML接口
• 外部依賴（對(duì)瀏覽器具體特性的依賴）
• 一些無意泄露的內(nèi)部實(shí)現(xiàn)

　　越往后的API，越隱晦，越不容易受到重視，但是一旦這些API發(fā)生變化，可能會(huì)導(dǎo)致調(diào)用方出現(xiàn)不符合預(yù)期甚至程序直接報(bào)錯(cuò)的情況。

　　Why API cannot be changed?

　　API是程序協(xié)同開發(fā)的重要保證，API的用戶希望API的提供方提供的是一段功能明確、接口明了的程序。更重要的是，用戶更期望在程序升級(jí)以后，他們能夠不經(jīng)思考地升級(jí)這些第三方代碼。

　　一旦上述提到的5個(gè)API中的任何一個(gè)發(fā)生變化，可能會(huì)給他們帶來巨大的代價(jià)，用戶需要排查所有調(diào)用的代碼，需要更改一些協(xié)議，需要調(diào)整所有與之相關(guān)的部分，這些工作對(duì)他們來說都是額外的，在預(yù)期之外的。如果辛辛苦苦完成這些以后，還在測(cè)試過程中發(fā)現(xiàn)了相關(guān)的bug，那對(duì)用戶的打擊就更大了。

　　如果API經(jīng)常發(fā)生變化，用戶就會(huì)失去對(duì)這段程序的信任，他們會(huì)更傾向自己獲得源代碼以后，按照自己的需求進(jìn)行修改，自行維護(hù)一個(gè)內(nèi)部的API比調(diào)用一個(gè)不斷發(fā)生變化的外部API要容易接受的多，雖然這樣做和我們協(xié)同開發(fā)、模塊化開發(fā)的初衷是完全相悖的。

　　最后，我們?yōu)槭裁匆薷腁PI呢？為了API看起來更加漂亮？為了提供更多有趣的功能？還是僅僅我們覺得到了改變了時(shí)候了？對(duì)于用戶來說，他們更愿意使用一個(gè)穩(wěn)定但是看起來不那么時(shí)髦的API，而不是使用一個(gè)很時(shí)髦，但是會(huì)經(jīng)常變動(dòng)的API。在這個(gè)問題上，項(xiàng)目開發(fā)者是實(shí)用派。但這并不意味著我們不再改進(jìn)API了，在后面，我會(huì)具體介紹如何能讓API保持穩(wěn)定的同時(shí)，讓API持續(xù)改進(jìn)。

　　Quality of API

　　在正式說兼容性之前，首先要明確一下，什么是好的API，因?yàn)閷?dǎo)致API的不兼容的根源總是來自一個(gè)想法：期望通過這次改變把API變得更好。

　　容易理解
　　如果一個(gè)API不能讓大多數(shù)使用者快速學(xué)會(huì)，這一定不是一個(gè)好的API。 比如ios的滑動(dòng)解鎖，老人和小孩都能都能一次解鎖，而Nokia的經(jīng)典兩鍵解鎖，你懂的。

　　一致性
　　一致性能大大降低用戶的學(xué)習(xí)和使用成本，用戶過去的努力學(xué)習(xí)，能持續(xù)的收效。

　　容易查找和學(xué)習(xí)
　　API必須要有文檔，并且介紹清晰，提供盡可能多的示例和可copy－paste的代碼，降低用戶的使用門檻。

　　提供簡(jiǎn)單的方案
　　API要能解決復(fù)雜的問題，提供很多可配置項(xiàng)，但是對(duì)于那些最常見的case，如果有一個(gè)簡(jiǎn)單的方案供給用戶使用，這樣能大大提高API的可用性

　　保護(hù)用戶在API上的已有工作
　　用戶過去在調(diào)用API、基于API開發(fā)所做的工作，這樣才能給用戶帶來價(jià)值的同時(shí)，不破壞他們過去的勞動(dòng)成果。

　　如何保證API的兼容

　　采用良好的設(shè)計(jì)思路

　　在設(shè)計(jì)過程中，如果能按照下面的方式來進(jìn)行設(shè)計(jì)，會(huì)讓這個(gè)API生命更長(zhǎng)久

• 面向用例的設(shè)計(jì)，收集用戶建議，把自己模擬成用戶，保證API設(shè)計(jì)的易用和合理
• 保證后續(xù)的需求可以通過擴(kuò)展的形式完成
• 第一版做盡量少的內(nèi)容，由于新需求可以通過擴(kuò)展的形式完成，因此盡量少做事情是抑制API設(shè)計(jì)錯(cuò)誤的一個(gè)有效方案
• 對(duì)外提供清晰的API和文檔規(guī)范，避免用戶錯(cuò)誤的使用API，尤其是避免API（見第一節(jié)）靠后級(jí)別的API被用戶知曉與誤用

　　除此之外，下面還列出了一些具體的設(shè)計(jì)方法：

• 方法優(yōu)于屬性
• 工廠方法優(yōu)于構(gòu)造函數(shù)
• 避免過多繼承
• 避免由于優(yōu)化或者復(fù)用代碼影響API
• 面向接口編程
• 擴(kuò)展參數(shù)應(yīng)當(dāng)是便利的
• 對(duì)組件進(jìn)行合理定位，確定暴露多少接口
• 提供擴(kuò)展點(diǎn)

　　有效的API評(píng)審

　　API設(shè)計(jì)完成以后，需要經(jīng)過周密的設(shè)計(jì)評(píng)審，評(píng)審的重點(diǎn)如下：

• 用例驅(qū)動(dòng)，評(píng)審前必須提供完善的使用用例，確保用例的合理性和完備性。
• 一致性，是否與系統(tǒng)中其他模塊的接口風(fēng)格一致，是否與對(duì)稱接口的設(shè)計(jì)一致。
• 簡(jiǎn)單明了，API應(yīng)該簡(jiǎn)單好理解，容易學(xué)習(xí)和使用的API才不容易被誤用，給我們帶來更多的麻煩。
• API盡可能少，如果一個(gè)API可以暴露也可以不暴露，那么就不要暴露他，等到用戶真正有需求的時(shí)候再將它成為一個(gè)公開接口也不遲。
• 支持持續(xù)改進(jìn)，API是否能夠方便地通過擴(kuò)展的方式增加功能和優(yōu)化。

　　把握API的生命周期

　　每一個(gè)API都是有生命周期的，我們需要讓API的生命周期更長(zhǎng)，并且在API的生命周期結(jié)束時(shí)能讓其平滑的消亡。

• 告訴用戶我們是如何設(shè)計(jì)的，避免誤用，提供指導(dǎo)，錯(cuò)誤的使用往往是縮短API壽命的一大殺手
• 提供試用期，API不可能一開始就是穩(wěn)定，經(jīng)過試用的API才能有更強(qiáng)的生命力
• 為API分級(jí)：內(nèi)部使用；二次開發(fā)使用；開發(fā)或試用中；穩(wěn)定；棄用API。避免API被濫用的同時(shí)，我們可以通過調(diào)整API的級(jí)別，來擴(kuò)大其影響力，也能更優(yōu)雅的結(jié)束一個(gè)API的生命周期。

　　保持API的逐步改善

　　過去我們總希望能將現(xiàn)有的不合理的設(shè)計(jì)完全推翻，然后按照現(xiàn)在美好的思路，重新設(shè)計(jì)這個(gè)API，但是在一段時(shí)間以后，又會(huì)碰到一樣的狀況，需要再推翻一次。 如果我們沒有有效的逐步改善的辦法，依靠推翻現(xiàn)有設(shè)計(jì)，重新設(shè)計(jì)API只能讓我們回到起點(diǎn)，然后重現(xiàn)之前的過程。 要有一套行之有效的持續(xù)改善的辦法來在API兼容的同時(shí)，改善API使之更好。

　　提高API的可測(cè)試性

　　API需要是可測(cè)試的，測(cè)試不應(yīng)依賴實(shí)現(xiàn)，測(cè)試充分的API，尤其是經(jīng)過了嚴(yán)格的兼容性整合測(cè)試的API，更能保證在升級(jí)的過程中不出現(xiàn)兼容性問題。

　　兼容性整合測(cè)試，是指一組測(cè)試用例集合，這組測(cè)試用例會(huì)站在使用者的立場(chǎng)上使用API。在API升級(jí)以后，再檢測(cè)這組測(cè)試用例是否能完全符合預(yù)期的通過測(cè)試，盡可能的發(fā)現(xiàn)兼容性問題。

　　避免極端的意見

　　在設(shè)計(jì)API的時(shí)候，一定要避免任何極端的意見，尤其是以下幾點(diǎn)：

• 必須漂亮
• API必須被正確地使用（用戶很難理解如何正確的使用API，API的設(shè)計(jì)者要充分考慮API被誤用的情況：如果一個(gè)API可能會(huì)被誤用，那么它一定會(huì)被誤用）
• 必須簡(jiǎn)單（我們總會(huì)面臨復(fù)雜的需求，能兩者兼顧的API是更好的API）
• 必須高性能（性能可以通過其他手段優(yōu)化，不應(yīng)該影響API的設(shè)計(jì)）
• 必須絕對(duì)兼容（盡管本文一直提到如何保證兼容，但是我們?nèi)匀灰庾R(shí)到，一些極少情況下會(huì)遇到的不兼容是可以容忍的）

　　一些具體的實(shí)施方案

　　在一個(gè)API不可避免要消亡或者改變的時(shí)候，我們應(yīng)該接受并且面對(duì)這個(gè)事實(shí)，下面列舉了幾種保證兼容性的前提下，對(duì)API進(jìn)行調(diào)整的辦法：

• 將API標(biāo)記為棄用，重新建立一個(gè)新的API。如果一個(gè)API不可避免要被消亡，這是唯一的辦法。
• 為其添加額外的參數(shù)或者參數(shù)選項(xiàng)來實(shí)現(xiàn)功能添加
• 將現(xiàn)有API拆成兩部分，提供一個(gè)精簡(jiǎn)的核心API，過去的API通過封裝核心API上實(shí)現(xiàn)。這通常用于解決用戶需要一個(gè)代碼精簡(jiǎn)的版本時(shí)。
• 在現(xiàn)有的API基礎(chǔ)上進(jìn)行封裝，提供一個(gè)功能更豐富的包或者類

　　小結(jié)

　　設(shè)計(jì)一個(gè)保持兼容的API是很困難的。在這之前，作者需要理解什么是API，以及如何評(píng)估API的質(zhì)量以后，通過良好的設(shè)計(jì)思路以及改進(jìn)方法，來保證API的向后兼容。

　　其他

　　事實(shí)上，Tangram base庫(kù)自從1.3.4版本以后，就已經(jīng)做到了API的向后兼容，如果對(duì)Tangram感興趣，可以前往Tangram網(wǎng)站查閱。

　　如果你對(duì)Javascript 的API兼容有什么自己的見解，歡迎留言討論。

it知識(shí)庫(kù)：如何做到API兼容，轉(zhuǎn)載需保留來源！

鄭重聲明：本文版權(quán)歸原作者所有，轉(zhuǎn)載文章僅為傳播更多信息之目的，如作者信息標(biāo)記有誤，請(qǐng)第一時(shí)間聯(lián)系我們修改或刪除，多謝。