優秀的API接口設計原則及方法（轉）

一旦API發生變化，就可能對相關的調用者帶來巨大的代價，用戶須要排查全部調用的代碼，須要調整全部與之相關的部分，這些工做對他們來講都是額外的。若是辛辛苦苦完成這些之後，還發現了相關的bug，那對用戶的打擊就更大。若是API常常發生變化，用戶就會失去對提供方失去信心，從而也會影響目前的業務。

可是咱們爲何還要修改API呢？爲了API看起來更加漂亮？爲了提供更多功能？爲了提供更好的性能？仍是僅僅以爲到了改變了時候了？對於用戶來講，他們更願意使用一個穩定可是看起來不那麼時髦的API，這並不意味着咱們再也不改進API了。當糟糕的API帶來的維護成本愈來愈大時，我想就是咱們去重構它的時候。

若是能夠回頭從新再作一遍，那麼我心目中的優秀的API應該是怎麼樣的？

判斷一個API是否優秀，並非簡單地根據第一個版本給出判斷的，而是要看隨着時間的推移，該API是否還能存在，是否仍舊保持得不錯。槽糕的API接口各類各樣，可是好的API接口對於用戶來講必須知足如下幾個點：

• 易學習：有完善的文檔及提供儘量多的示例和可copy－paste的代碼，像其餘設計工做同樣，你應該應用最小驚訝原則。
• 易使用：沒有複雜的程序、複雜的細節，易於學習；靈活的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進行調整的辦法：

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

一些好的API示例：

1. Flickr API，這裏是文檔的示例，同時提供了一個很是方便的API測試工具。
2. Mediawiki API
3. Ebay API，這裏有一個很是詳盡的文檔示例。

原文連接：http://www.biaodianfu.com/how-to-design-a-good-api.html

 

 

　　在手機普遍流行的今天，手機應用也隨之愈來愈多，並且成長的速度也很是快。手機應用軟件開發實現方式同普通PC軟件同樣，也分爲BS和CS方式。而採用CS方式，在服務器端大多采用接口的形式提供數據交互(主流數據交互方式有：Json、WebService等)，今天要說的就是如何設計接口。

　　接口做爲連通客戶端與數據庫進行數據流通的橋樑，起着舉足輕重的做用，直接影響着程序的效率性、穩定性、可靠性以及數據的正確性、完整性。客戶端注重的是界面美觀，操做方便順暢，是用戶最直接的感覺體驗，而接口則是全部數據的提供者，是用戶深層的內涵體驗。

　　因次，設計接口在一個項目中，是很是重要的。那麼我就目前的經驗總結下如何合理設計接口。

　　1、 設計原理

　　1. 深刻了解需求

　　除了設計數據庫的人最瞭解需求外，其次就是設計接口的人了，甚至有時接口開發人員還要參與到數據庫設計中。從「客戶端-接口-數據庫」的層次上看，接口明顯扮演着承上啓下的角色，一方面要明白接口要什麼數據，另外一方面要考慮如何從數據庫獲取、組織數據。因此若是不瞭解需求，你就沒法正確抽象對象來組織數據給客戶端，也沒法驗證數據庫的數據結構可否知足需求。數據庫設計者要了解需求中的數據結構，而接口則更多的要了解需求中的邏輯結構以及由此衍生出的邏輯數據結構。

　　2. 瞭解數據庫結構

　　既然接口要明白如何從數據庫獲取、組織數據，就固然要了解數據庫結構啦。

　　3. 瞭解客戶端原型

　　瞭解原型，其實更可能是爲了幫助你設計接口時須要提供的數據和結構。但有時當你設計時並無原型，因此此條並非必需要求的。但假如設計完接口後原型出來了，咱們也能夠拿原型還驗證接口設計是否正確、合理。

　　2、設計原則

　　1. 充分理由

　　不是隨便一個功能就要有個接口，也不是隨便一個需求就要加個接口。每新建一個接口，就要有充分的理由和考慮，即這個接口的存在是十分有意義額價值的，無心義的接口不只增長了維護的難度，更重要是對於程序的可控性的大大下降，接口也會十分臃腫。所以我放在了第一條。

　　2. 職責明確

　　一個接口只負責一個業務功能，它與設計模式裏的職責單一原則相似但卻不一樣，由於一個業務功能裏可能會包含多個操做，好比查詢會員，可能除了查詢會員表外還要獲取該會員的其餘必要信息，但不要在查詢會員的同時還有修改權限等相似的其餘業務功能，應該分紅兩個接口還作。

　　3. 高內聚低耦合

　　一個接口要包含完整的業務功能，而不一樣接口之間的業務關聯要儘量的小。仍是查詢會員的例子，有時查詢會員的同時，可能該會員的相關信息要隨之發生變化(如狀態)，若是這時一條完整的業務流水線，那麼就應該在一個接口裏完成，而不該再單獨設立接口去操做完成。就是說一個接口不該該隨着另外一個變化而變化或以某幾個接口爲前提而存在。

　　4. 分析角度明確

　　設計接口分析的角度要統一明確。不然會形成接口結構的混亂。例如，不要一會以角色的角度設計，一下子就要以功能的角度設計。

　　5. 入參格式統一

　　全部接口的參數格式要求及風格要統一，不要一個接口參數是逗號分隔，另外一個就是數組;不要一個接口日期參數是x年x月x日風格，另外一個就是x-x-x。

　　6. 狀態及消息

　　提供必要的接口調用狀態信息。調用是否成功?若是失敗，那麼失敗的緣由是什麼。這些必要的信息必需要告訴給客戶端。

　　7. 控制數據量

　　一個接口返回不該該包含過多的數據量，過多的數據量不只處理複雜，對數據傳輸的壓力也很是大，會致使客戶端反應緩慢。過多的數據量不少時候都是接口劃分不明確。

　　8. 禁止隨意拓展參數

　　與第1條相似，只不過是針對參數而言了。往後拓展接口多是難以免的，可是不要隨意就加參數，加參數必定是必要且有意義的，需求改變前首先應考慮現有接口內部維護是否能知足需求，而不要經過加個參數來方便本身實現需求的難度，由於參數的更變會直接致使客戶端調用的變化，容易產生版本兼容性問題。

　　3、設計方法

　　1. 抽象業務

　　相比抽象對象而言，抽象業務更宏觀，我以爲相對也容易一些，但抽象尺度每每不太好把握。

　　2. 數據格式

　　接口定義的數據格式必須都通過充分考慮，不然會出現數據轉換失敗或超出長度等錯誤。若是沒法肯定，直接設置成字符串是最合適的。

　　3. 有意義的命名

　　不管是接口仍是參數，名稱都應該是有意義的，讓人能看明白的。

　　總之，接口設計是一個細緻的工做，設計時也會有不少矛盾，但我的傾向於粗粒度設計方向(即內聚性更高一些)，這樣不只給客戶端瀏覽接口方便明確，維護也輕鬆些，這麼作的缺點就是某一接口擴展時不是很靈活，但能夠經過從新定義一個接口來彌補，但正如上所說，新增接口仍是要三思然後行的。以上不少雖然都是理論性講解，但緊緊記住這些，並結合實際工做，就會慢慢深入的體會到其中的含義。即理論指導實踐，實踐來驗證理論。

 

轉：連接