本文主要介紹什麼是API,以及API兼容的重要性,最終給出方案如何評估API,以及如何做到API兼容。
API的全稱是application programming interface。
而很多時候,程序開發者僅僅把函數、類的接口做為API的一部分,而忽略了其他重要的編程接口。
事實上,在前端Javscript編程中常見的API包括:
越往後的API,越隱晦,越不容易受到重視,但是一旦這些API發生變化,可能會導致調用方出現不符合預期甚至程序直接報錯的情況。
API是程序協同開發的重要保證,API的用戶希望API的提供方提供的是一段功能明確、接口明了的程序。更重要的是,用戶更期望在程序升級以後,他們能夠“不經思考”地升級這些第三方代碼。
一旦上述提到的5個API中的任何一個發生變化,可能會給他們帶來巨大的代價,用戶需要排查所有調用的代碼,需要更改一些協議,需要調整所有與之相關的部分,這些工作對他們來說都是額外的,在預期之外的。如果辛辛苦苦完成這些以後,還在測試過程中發現了相關的bug,那對用戶的打擊就更大了。
如果API經常發生變化,用戶就會失去對這段程序的信任,他們會更傾向自己獲得源代碼以後,按照自己的需求進行修改,自行維護一個內部的API比調用一個不斷發生變化的外部API要容易接受的多,雖然這樣做和我們協同開發、模塊化開發的初衷是完全相悖的。
最後,我們為什麼要修改API呢?為了API看起來更加漂亮?為了提供更多有趣的功能?還是僅僅我們覺得到了改變了時候了?對於用戶來說,他們更願意使用一個穩定但是看起來不那麼時髦的API,而不是使用一個很時髦,但是會經常變動的API。在這個問題上,項目開發者是實用派。但這並不意味著我們不再改進API了,在後面,我會具體介紹如何能讓API保持穩定的同時,讓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的向後兼容。
事實上,Tangram base庫自從1.3.4版本以後,就已經做到了API的向後兼容,如果對Tangram感興趣,可以前往Tangram網站查閱。
如果你對Javascript 的API兼容有什麼自己的見解,歡迎留言討論。