#### 1.為什么要設計API 什么是API呢？API的全稱是：應用程序編程接口（Application Programming Interface），既然是接口，必然要涉及到至少兩個方面：使用方、提供方。 有人的地方就有溝通，有程序的地方就有互相調用。如果說語言是人與人之間溝通的橋梁，那么API則是程序間調用的“橋梁”。 規模越大的程序中，API數量就會越多，API的質量高低決定了程序的可讀性、易用性。設計一套（或多套）優秀的API能為整體帶來良好的代碼閱讀體驗以及高效的開發效率，同時這也應該是一個優秀程序員的必備條件。 ### 2.如何評價API的好壞 我們來簡單的看下如何評價一個API的好與不好。 #### 2.1 名稱及參數 方法名稱是否可以自描述，即看到方法的名字就能知道方法的作用、看到參數名就知道需要傳遞什么樣的數據（比如getUserById(String userId)）。 #### 2.2 協議及行為 API會涉及到協議嗎？答案是肯定的。一個方法的輸入、輸出就是協議，什么樣的輸入是合法的、什么樣的輸入是非法的，針對合法的輸入在處理后返回什么樣的結果、針對非法的輸入返回什么樣的提示以便能快速知道問題的癥結所在。 同時協議也要保證在不同版本間的兼容，新版本要兼容老版本，保證之前的調用方不會因為API的內部修改而不能得到正確的結果。 所謂行為就是API內部實現邏輯，有些時候，雖然我們提供給用戶的是API，但是內部邏輯也在用戶的可見范圍內，這時候用戶會查看內部實現并根據API內部實現編寫自己的代碼，因此內部行為的穩定同樣很重要。 #### 2.3 可理解及一致性 API一定要便于使用者理解，這樣才是廣泛傳播的基礎。如果有些API需要用戶掌握特定的概念、定義，那么就要保持這個API的一致性，不能輕易的改變API，否則會給使用者帶來很大的麻煩。 ### 3. API設計的一些原則 #### 3.1 只公開必須的內容 在編寫API時，肯定會有這樣一種思考方式：是不是要多加一個參數呢？可能會有這種用法吧？參數要不要做到很靈活呢？接收一個Object數組吧（而且是不帶泛型的）。。。有這樣的想法能說明我們在設計API的時候思考了很多，那么我們應該怎么做呢？精簡、明確、直接。只公開必要的內容，不要為了“以后可能會有”而大傷腦筋，考慮未來的擴展固然是好事，但過猶不及凡事總要有個度。 #### 3.2 面向接口編程 面向接口編程，在一些面向對象語言中提及的比較多（比如java）。面向接口編程，就是在參數的傳遞和返回使用接口而不是實現類，這樣可以方便的替換實現方，從而達到程序容易擴展、實現更加靈活的目的。 比如我們在設計一個API的時候，傳入參數使用接口Map就會比使用具體的類如HashMap、TreeMap更加靈活。比如JDBC，我們使用的都是Connection、ResultSet這樣的一些接口，具體的實現則由數據庫廠商提供，MySql、Oracle等廠商都提供了JDBC的實現。 #### 3.3 方法重載 方法重載在很多API、SDK中有著廣泛的使用，之所有使用重載是因為它為程序實現帶來了極大的便利。一個明顯的例子是：在不同的地方做相同或類似的事情，重載這種方式的優越性就凸顯出來了。我們看下面的例子： 在JDK的java.util包下的Collections類有兩個個排序的靜態方法： ~~~ sort(List<T> list)； sort(List<T> list, Comparator<? super T> c); ~~~ 同樣的方法名不會讓人疑惑，參數的豐富讓人一眼就能看到重載方法的區別以及自己該調用哪個。 #### 3.4 返回值 當API具有返回值時，應該在一組（或同一種類）的API中使用同樣規則的返回值。 下面提供一種參考方式：如返回的結果是單個對象，當沒有找到符合條件的結果時，應返回null；如果返回值是List、Map或數組，那么應該返回空的Lisp、Map、數組，而不是null。 上面的方式不一定是適合所有場景的，也可以使用另外的一種通用規則替代，比如當查詢不到符合條件的數據時拋出異常，這也是一種通用的方式，具體使用哪種，根據實際情況而定。 * * * * * 作者： moocer 鏈接：http://www.imooc.com/article/15611 來源：慕課網 本文原創發布于慕課網 ，轉載請注明出處，謝謝合作！