一旦API發(fā)生變化，就可能對相關(guān)的調(diào)用者帶來巨大的代價，用戶需要排查所有調(diào)用的代碼，需要調(diào)整所有與之相關(guān)的部分，這些工作對他們來說都是額外的。如果辛辛苦苦完成這些以后，還發(fā)現(xiàn)了相關(guān)的bug，那對用戶的打擊就更大。如果API經(jīng)常發(fā)生變化，用戶就會失去對提供方失去信心，從而也會影響目前的業(yè)務(wù)。

但是我們?yōu)槭裁催€要修改API呢？為了API看起來更加漂亮？為了提供更多功能？為了提供更好的性能？還是僅僅覺得到了改變了時候了？對于用戶來說，他們更愿意使用一個穩(wěn)定但是看起來不那么時髦的API，這并不意味著我們不再改進API了。當(dāng)糟糕的API帶來的維護成本越來越大時，我想就是我們?nèi)ブ貥?gòu)它的時候。

如果可以回頭重新再做一遍，那么我心目中的優(yōu)秀的API應(yīng)該是怎么樣的？

判斷一個API是否優(yōu)秀，并不是簡單地根據(jù)第一個版本給出判斷的，而是要看隨著時間的推移，該API是否還能存在，是否仍舊保持得不錯。槽糕的API接口各種各樣，但是好的API接口對于用戶來說必須滿足以下幾個點：

• 易學(xué)習(xí)：有完善的文檔及提供盡可能多的示例和可copy－paste的代碼，像其他設(shè)計工作一樣，你應(yīng)該應(yīng)用最小驚訝原則。
• 易使用：沒有復(fù)雜的程序、復(fù)雜的細節(jié)，易于學(xué)習(xí)；靈活的API允許按字段排序、可自定義分頁、 排序和篩選等。一個完整的API意味著被期望的功能都包含在內(nèi)。
• 難誤用：對詳細的錯誤提示，有些經(jīng)驗的用戶可以直接使用API而不需要閱讀文檔。

而對于開發(fā)人員來說，要求又是不一樣的：

• 易閱讀：代碼的編寫只需要一次一次，但是當(dāng)調(diào)試或者修改的時候都需要對代碼進行閱讀。
• 易開發(fā)：個最小化的接口是使用盡可能少的類以及盡可能少的類成員。這樣使得理解、記憶、調(diào)試以及改變API更容易。

如何做到以上幾點，以下是一些總結(jié)：

1、?面向用例設(shè)計

如果一個API被廣泛使用了，那么就不可能了解所有使用該API的用戶。如果設(shè)計者希望能夠設(shè)計出被廣泛使用的API，那么必須站在用戶的角度來理解如何設(shè)計API庫，以及如何才能設(shè)計出這樣的API庫。

2、?采用良好的設(shè)計思路

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

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

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

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

3、?避免極端的意見

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

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

4、?有效的API評審

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

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

5、?提高API的可測試性

API需要是可測試的，測試不應(yīng)依賴實現(xiàn)，測試充分的API，尤其是經(jīng)過了嚴(yán)格的“兼容性整合測試”的API，更能保證在升級的過程中不出現(xiàn)兼容性問題。兼容性整合測試，是指一組測試用例集合，這組測試用例會站在使用者的立場上使用API。在API升級以后，再檢測這組測試用例是否能完全符合預(yù)期的通過測試，盡可能的發(fā)現(xiàn)兼容性問題。

6、?保證API的向后兼容

對于每一個API的設(shè)計者來說，都渴望做到“向后兼容”，因為不管是現(xiàn)在的API用戶，還是潛在的API用戶，都只信任那些可兼容的API。但向后兼容有多個層次上的意義，而且不同層次的向后兼容，也意味著不同的重要性和復(fù)雜度。

7、?保持逐步改善

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

8、?把握API的生命周期

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

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

開發(fā)API的過程其實就是一個溝通交流的過程。溝通的雙方就是API用戶和API設(shè)計者。

9、?一些具體的實施方案

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

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

一些好的API示例：

Flickr API，這里是文檔的示例，同時提供了一個非常方便的API測試工具。

Mediawiki API

Ebay API，這里有一個非常詳盡的文檔示例。

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

　　在手機廣泛流行的今天，手機應(yīng)用也隨之越來越多，而且成長的速度也非?？?。手機應(yīng)用軟件開發(fā)實現(xiàn)方式同普通PC軟件一樣，也分為BS和CS方式。而采用CS方式，在服務(wù)器端大多采用接口的形式提供數(shù)據(jù)交互(主流數(shù)據(jù)交互方式有：Json、WebService等)，今天要說的就是如何設(shè)計接口。

　　接口作為連通客戶端與數(shù)據(jù)庫進行數(shù)據(jù)流通的橋梁，起著舉足輕重的作用，直接影響著程序的效率性、穩(wěn)定性、可靠性以及數(shù)據(jù)的正確性、完整性?？蛻舳俗⒅氐氖墙缑婷烙^，操作方便順暢，是用戶最直接的感受體驗，而接口則是所有數(shù)據(jù)的提供者，是用戶深層的內(nèi)涵體驗。

　　因次，設(shè)計接口在一個項目中，是非常重要的。那么我就目前的經(jīng)驗總結(jié)下如何合理設(shè)計接口。

　　一、 設(shè)計原理

　　1. 深入了解需求

　　除了設(shè)計數(shù)據(jù)庫的人最了解需求外，其次就是設(shè)計接口的人了，甚至有時接口開發(fā)人員還要參與到數(shù)據(jù)庫設(shè)計中。從“客戶端-接口-數(shù)據(jù)庫”的層次上看，接口明顯扮演著承上啟下的角色，一方面要明白接口要什么數(shù)據(jù)，另一方面要考慮如何從數(shù)據(jù)庫獲取、組織數(shù)據(jù)。所以如果不了解需求，你就無法正確抽象對象來組織數(shù)據(jù)給客戶端，也無法驗證數(shù)據(jù)庫的數(shù)據(jù)結(jié)構(gòu)能否滿足需求。數(shù)據(jù)庫設(shè)計者要了解需求中的數(shù)據(jù)結(jié)構(gòu)，而接口則更多的要了解需求中的邏輯結(jié)構(gòu)以及由此衍生出的邏輯數(shù)據(jù)結(jié)構(gòu)。

　　2. 了解數(shù)據(jù)庫結(jié)構(gòu)

　　既然接口要明白如何從數(shù)據(jù)庫獲取、組織數(shù)據(jù)，就當(dāng)然要了解數(shù)據(jù)庫結(jié)構(gòu)啦。

　　3. 了解客戶端原型

　　了解原型，其實更多是為了幫助你設(shè)計接口時需要提供的數(shù)據(jù)和結(jié)構(gòu)。但有時當(dāng)你設(shè)計時并沒有原型，所以此條并不是必須要求的。但假如設(shè)計完接口后原型出來了，我們也可以拿原型還驗證接口設(shè)計是否正確、合理。

　　二、設(shè)計原則

　　1. 充分理由

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

　　2. 職責(zé)明確

　　一個接口只負責(zé)一個業(yè)務(wù)功能，它與設(shè)計模式里的職責(zé)單一原則類似但卻不同，因為一個業(yè)務(wù)功能里可能會包含多個操作，比如查詢會員，可能除了查詢會員表外還要獲取該會員的其他必要信息，但不要在查詢會員的同時還有修改權(quán)限等類似的其他業(yè)務(wù)功能，應(yīng)該分成兩個接口還做。

　　3. 高內(nèi)聚低耦合

　　一個接口要包含完整的業(yè)務(wù)功能，而不同接口之間的業(yè)務(wù)關(guān)聯(lián)要盡可能的小。還是查詢會員的例子，有時查詢會員的同時，可能該會員的相關(guān)信息要隨之發(fā)生變化(如狀態(tài))，如果這時一條完整的業(yè)務(wù)流水線，那么就應(yīng)該在一個接口里完成，而不應(yīng)再單獨設(shè)立接口去操作完成。就是說一個接口不應(yīng)該隨著另一個變化而變化或以某幾個接口為前提而存在。

　　4. 分析角度明確

　　設(shè)計接口分析的角度要統(tǒng)一明確。否則會造成接口結(jié)構(gòu)的混亂。例如，不要一會以角色的角度設(shè)計，一會兒就要以功能的角度設(shè)計。

　　5. 入?yún)⒏袷浇y(tǒng)一

　　所有接口的參數(shù)格式要求及風(fēng)格要統(tǒng)一，不要一個接口參數(shù)是逗號分隔，另一個就是數(shù)組;不要一個接口日期參數(shù)是x年x月x日風(fēng)格，另一個就是x-x-x。

　　6. 狀態(tài)及消息

　　提供必要的接口調(diào)用狀態(tài)信息。調(diào)用是否成功?如果失敗，那么失敗的原因是什么。這些必要的信息必須要告訴給客戶端。

　　7. 控制數(shù)據(jù)量

　　一個接口返回不應(yīng)該包含過多的數(shù)據(jù)量，過多的數(shù)據(jù)量不僅處理復(fù)雜，對數(shù)據(jù)傳輸?shù)膲毫σ卜浅４?#xff0c;會導(dǎo)致客戶端反應(yīng)緩慢。過多的數(shù)據(jù)量很多時候都是接口劃分不明確。

　　8. 禁止隨意拓展參數(shù)

　　與第1條類似，只不過是針對參數(shù)而言了。日后拓展接口可能是難以避免的，但是不要隨意就加參數(shù)，加參數(shù)一定是必要且有意義的，需求改變前首先應(yīng)考慮現(xiàn)有接口內(nèi)部維護是否能滿足需求，而不要通過加個參數(shù)來方便自己實現(xiàn)需求的難度，因為參數(shù)的更變會直接導(dǎo)致客戶端調(diào)用的變化，容易產(chǎn)生版本兼容性問題。

　　三、設(shè)計方法

　　1. 抽象業(yè)務(wù)

　　相比抽象對象而言，抽象業(yè)務(wù)更宏觀，我覺得相對也容易一些，但抽象尺度往往不太好把握。

　　2. 數(shù)據(jù)格式

　　接口定義的數(shù)據(jù)格式必須都經(jīng)過充分考慮，否則會出現(xiàn)數(shù)據(jù)轉(zhuǎn)換失敗或超出長度等錯誤。如果無法確定，直接設(shè)置成字符串是最合適的。

　　3. 有意義的命名

　　無論是接口還是參數(shù)，名稱都應(yīng)該是有意義的，讓人能看明白的。

　　總之，接口設(shè)計是一個細致的工作，設(shè)計時也會有很多矛盾，但個人傾向于粗粒度設(shè)計方向(即內(nèi)聚性更高一些)，這樣不僅給客戶端瀏覽接口方便明確，維護也輕松些，這么做的缺點就是某一接口擴展時不是很靈活，但可以通過重新定義一個接口來彌補，但正如上所說，新增接口還是要三思而后行的。以上很多雖然都是理論性講解，但牢牢記住這些，并結(jié)合實際工作，就會慢慢深刻的體會到其中的含義。即理論指導(dǎo)實踐，實踐來驗證理論。

總結(jié)

以上是生活随笔為你收集整理的优秀的API接口设计原则及方法的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。