如何做到API兼容

來源: 百度泛用戶體驗  發布時間: 2011-11-09 14:14  閱讀: 3139 次  推薦: 0   原文鏈接   [收藏]  
摘要:本文主要介紹什么是API,以及API兼容的重要性,最終給出方案如何評估API,以及如何做到API兼容。

  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兼容有什么自己的見解,歡迎留言討論。

0
0
 
標簽:API
 
 

文章列表

arrow
arrow
    全站熱搜
    創作者介紹
    創作者 大師兄 的頭像
    大師兄

    IT工程師數位筆記本

    大師兄 發表在 痞客邦 留言(0) 人氣()