Whats API?

　　API的全稱是application programming interface。

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

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

• 函數、類接口，包括參數，返回值，函數對外部對象（常常是DOM）的具體操作等
• 網絡接口協議，如和后端交互的JSON、XML數據格式，或者script回調中的函數名
• 樣式以及HTML接口
• 外部依賴（對瀏覽器具體特性的依賴）
• 一些無意泄露的內部實現

　　越往后的API，越隱晦，越不容易受到重視，但是一旦這些API發生變化，可能會導致調用方出現不符合預期甚至程序直接報錯的情況。

　　Why API cannot be changed?

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

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

　　如果API經常發生變化，用戶就會失去對這段程序的信任，他們會更傾向自己獲得源代碼以后，按照自己的需求進行修改，自行維護一個內部的API比調用一個不斷發生變化的外部API要容易接受的多，雖然這樣做和我們協同開發、模塊化開發的初衷是完全相悖的。

　　最后，我們為什么要修改API呢？為了API看起來更加漂亮？為了提供更多有趣的功能？還是僅僅我們覺得到了改變了時候了？對于用戶來說，他們更愿意使用一個穩定但是看起來不那么時髦的API，而不是使用一個很時髦，但是會經常變動的API。在這個問題上，項目開發者是實用派。但這并不意味著我們不再改進API了，在后面，我會具體介紹如何能讓API保持穩定的同時，讓API持續改進。

　　Quality of API

　　在正式說兼容性之前，首先要明確一下，什么是好的API，因為導致API的不兼容的根源總是來自一個想法：期望通過這次改變把API變得更好。

　　容易理解
　　如果一個API不能讓大多數使用者快速學會，這一定不是一個好的API。 比如iOS的滑動解鎖，老人和小孩都能都能一次解鎖，而Nokia的經典兩鍵解鎖，你懂的。

　　一致性
　　一致性能大大降低用戶的學習和使用成本，用戶過去的努力學習，能持續的收效。

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

　　提供簡單的方案
　　API要能解決復雜的問題，提供很多可配置項，但是對于那些最常見的case，如果有一個簡單的方案供給用戶使用，這樣能大大提高API的可用性

　　保護用戶在API上的已有工作
　　用戶過去在調用API、基于API開發所做的工作，這樣才能給用戶帶來價值的同時，不破壞他們過去的勞動成果。

　　如何保證API的兼容

　　采用良好的設計思路

　　在設計過程中，如果能按照下面的方式來進行設計，會讓這個API生命更長久

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

　　除此之外，下面還列出了一些具體的設計方法：

• 方法優于屬性
• 工廠方法優于構造函數
• 避免過多繼承
• 避免由于優化或者復用代碼影響API
• 面向接口編程
• 擴展參數應當是便利的
• 對組件進行合理定位，確定暴露多少接口
• 提供擴展點

　　有效的API評審

　　API設計完成以后，需要經過周密的設計評審，評審的重點如下：

• 用例驅動，評審前必須提供完善的使用用例，確保用例的合理性和完備性。
• 一致性，是否與系統中其他模塊的接口風格一致，是否與對稱接口的設計一致。
• 簡單明了，API應該簡單好理解，容易學習和使用的API才不容易被誤用，給我們帶來更多的麻煩。
• API盡可能少，如果一個API可以暴露也可以不暴露，那么就不要暴露他，等到用戶真正有需求的時候再將它成為一個公開接口也不遲。
• 支持持續改進，API是否能夠方便地通過擴展的方式增加功能和優化。

　　把握API的生命周期

　　每一個API都是有生命周期的，我們需要讓API的生命周期更長，并且在API的生命周期結束時能讓其平滑的消亡。

• 告訴用戶我們是如何設計的，避免誤用，提供指導，錯誤的使用往往是縮短API壽命的一大殺手
• 提供試用期，API不可能一開始就是穩定，經過試用的API才能有更強的生命力
• 為API分級：內部使用；二次開發使用；開發或試用中；穩定；棄用API。避免API被濫用的同時，我們可以通過調整API的級別，來擴大其影響力，也能更優雅的結束一個API的生命周期。

　　保持API的逐步改善

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

　　提高API的可測試性

　　API需要是可測試的，測試不應依賴實現，測試充分的API，尤其是經過了嚴格的兼容性整合測試的API，更能保證在升級的過程中不出現兼容性問題。

　　兼容性整合測試，是指一組測試用例集合，這組測試用例會站在使用者的立場上使用API。在API升級以后，再檢測這組測試用例是否能完全符合預期的通過測試，盡可能的發現兼容性問題。

　　避免極端的意見

　　在設計API的時候，一定要避免任何極端的意見，尤其是以下幾點：

• 必須漂亮
• API必須被正確地使用（用戶很難理解如何正確的使用API，API的設計者要充分考慮API被誤用的情況：如果一個API可能會被誤用，那么它一定會被誤用）
• 必須簡單（我們總會面臨復雜的需求，能兩者兼顧的API是更好的API）
• 必須高性能（性能可以通過其他手段優化，不應該影響API的設計）
• 必須絕對兼容（盡管本文一直提到如何保證兼容，但是我們仍然要意識到，一些極少情況下會遇到的不兼容是可以容忍的）

　　一些具體的實施方案

　　在一個API不可避免要消亡或者改變的時候，我們應該接受并且面對這個事實，下面列舉了幾種保證兼容性的前提下，對API進行調整的辦法：

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

　　小結

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

　　其他

　　事實上，Tangram base庫自從1.3.4版本以后，就已經做到了API的向后兼容，如果對Tangram感興趣，可以前往Tangram網站查閱。

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