Java API設計CheckList

API設計原則：正確、好名、易用、易學、夠快、夠小。但咱們歷來不缺原則，〜〜〜

Interface

1.The Importance of Being Use Case Oriented，一個接口應當是一組方法的集合，方法是否能放在一塊兒、最重要的依據是經過用測和使用場景去判斷。更具體地是The Input Params Oriented，輸入參數必定與接口相關。

2.you can't know what users of your API will do with it.但瞭解接口的可能調用者狀況，預測使用場景，考慮性能壓力。使用場景包括：WHO、WHY、WHERE、WHEN、HOW等，e.g.[APP團購單詳情頁][爲了獲取商戶詳情][在團購列表頁][當該用戶未購買過該團購單時][經過傳Enum.Type.Mobile&shopId方式]調用shpinfo.bin接口。性能壓力，各渠道調用QPS等。另外還需考慮線程安全，如synchronized等。

3.版本控制。 bring out one or more 0.x versions. create a new API with different package names. 不穩定版本、採用小號方式，讓用戶知道」我是壞人「。若是歷史包袱過重，那就乾脆換個包，令新、舊API和諧共存。另外，你永遠均可以新增API，但永遠都不能刪除。

4.考慮提供批量處理方法，批處理能夠有效減小網絡傳輸、增長處理效率等。應當在批處理以前定義單個操做。

5.接口應該保證冪等性，異步調用超時、可保證重複調用，如AddConsum(serialNo, user, product, money)，增長serialNo避免重複提交。

6.屏蔽底層實現細節。不要過分地具體說明方法的行爲，如：用Map、List替換HashMap、ArrayList等，Exceptions should usually be unchecked。

 

Class

7.接口類使用到的全部實體類/Bean等類，爲之提供無參數的構造函數。 一些框架如hessian須要bean有無參的構造函數。

8.接口方法中避免重載的方法，即避免有兩個方法同名，重載的方法一個方面在hessian接口調用會有問題（其餘協議的遠程接口可能也有問題），另外一個方面同名的方法影響代碼可讀性。 好比這樣的接口是不合適的。

9.接口中用到的自定義類， 實現序列化接口，提供toString()方法; Java要提供toString()方法，並繼承Serializable接口，生成Serial Verion UID。考慮實現Comparable等接口。

10.禁止使用繼承，在實現類前加final關鍵字。繼承違反了encapsulation特性，子類必須知道父類的實現特性。

Method

11.採用合適的參數和返回數據類型。如：使用BigDecimal或double代替float(32bit)，使用更加靈活的接口數據類型做爲輸入參數，儘可能使用Enum代替String做爲類型區分參數等。

12.避免過長的參數列表，專家建議不超過3個，歡迎拍磚。有兩種技術避免過長參數：a.將一個多個步聚的方法拆分細化，b.建立包含這些參數的幫助類。

13.避免集合返回NULL，應當返回空對象。但對於單個對象，若是空對象不可以方便地表達「值爲NULL」的狀態，則返回NULL。

附：

GOOGLE首席軟件工程師Joshua Bloch：《How to Design a Good API and Why it Matters》《深刻JAVA虛擬機》的做者Bill Venners：《Interface Design》