來自Google資深工程師的API設計最佳實踐

來自Google資深工程師Joshua Bloch的分享：API設計最佳實踐

爲何API設計如此重要？API是一個公司最重要的資產。

爲何API的設計對程序員如此重要？

API一旦發佈，出於兼容性考慮，不能輕易地爲所欲爲進行修改，好比刪除參數。

從API的上帝 - 設計者的視角出發，有助於提升代碼質量。

一個優秀的API應該知足下列標準：

易學易用，甚至是自描述的，不需文檔也能讓新手快速上手。不易形成誤解。後續維護者易於理解，知足開閉原則 - 可以很容易進行擴展。

如何設計一個好的API

首先應該從收集需求出發。注意結合API實現的複雜度一塊兒考慮。

做爲第一步，首先給出需求規格文檔，一頁便可：

別期望你的API能讓全部人滿意。也不要期望發佈後，它不會出任何錯誤——那是不可能的。

API也應該遵循單一職責：若是你發覺很難根據你的API實現的功能給它取個合適的名字，這是一個很差的信號，不少時候說明你的API裏面作了太多事情——試着把它們拆成多個API。

信息封裝 - 公有類儘可能避免暴露公有字段出去，最大化信息隱藏

API命名藝術 - API的名稱也是一門語言。

API和文檔的關係

合理使用繼承和子類，不要濫用里氏替換原則

採用fail fast 策略，儘量早地拋出錯誤消息：

API的數據都應該容許使用者經過字符串的方式訪問

慎用重載

選用合適的API參數和返回類型

API裏的參數順序也頗有講究

避免冗長的參數列表，參數若是超過3個，使用者就須要經過閱讀文檔才能消費了。

儘可能返回不須要調用者進行異常處理的參數，好比空數組或集合，而不是null

API設計裏的和異常處理相關的最佳實踐

API重構的最佳實踐

API設計和Thread-local相關的最佳實踐

要獲取更多Jerry的原創文章，請關注公衆號"汪子熙":