來自Google資深工程師的API設(shè)計(jì)最佳實(shí)踐

來自Google資深工程師Joshua Bloch的分享：API設(shè)計(jì)最佳實(shí)踐

為什么API設(shè)計(jì)如此重要？API是一個(gè)公司最重要的資產(chǎn)。

為什么API的設(shè)計(jì)對程序員如此重要？

API一旦發(fā)布，出于兼容性考慮，不能輕易地隨心所欲進(jìn)行修改，比如刪除參數(shù)。

從API的上帝 - 設(shè)計(jì)者的視角出發(fā)，有助于提高代碼質(zhì)量。

一個(gè)優(yōu)秀的API應(yīng)該滿足下列標(biāo)準(zhǔn)：

易學(xué)易用，甚至是自描述的，不需文檔也能讓新手快速上手。不易造成誤解。后續(xù)維護(hù)者易于理解，滿足開閉原則 - 能夠很容易進(jìn)行擴(kuò)展。

如何設(shè)計(jì)一個(gè)好的API

首先應(yīng)該從收集需求出發(fā)。注意結(jié)合API實(shí)現(xiàn)的復(fù)雜度一起考慮。

作為第一步，首先給出需求規(guī)格文檔，一頁即可：

別指望你的API能讓所有人滿意。也不要指望發(fā)布后，它不會(huì)出任何錯(cuò)誤——那是不可能的。

API也應(yīng)該遵循單一職責(zé)：如果你發(fā)覺很難根據(jù)你的API實(shí)現(xiàn)的功能給它取個(gè)合適的名字，這是一個(gè)不好的信號(hào)，很多時(shí)候說明你的API里面做了太多事情——試著把它們拆成多個(gè)API。

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

API命名藝術(shù) - API的名稱也是一門語言。

API和文檔的關(guān)系

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

采用fail fast 策略，盡可能早地拋出錯(cuò)誤消息：

API的數(shù)據(jù)都應(yīng)該允許使用者通過字符串的方式訪問

慎用重載

選用合適的API參數(shù)和返回類型

API里的參數(shù)順序也很有講究

避免冗長的參數(shù)列表，參數(shù)如果超過3個(gè)，使用者就需要通過閱讀文檔才能消費(fèi)了。

盡量返回不需要調(diào)用者進(jìn)行異常處理的參數(shù)，比如空數(shù)組或集合，而不是null

API設(shè)計(jì)里的和異常處理相關(guān)的最佳實(shí)踐

API重構(gòu)的最佳實(shí)踐

API設(shè)計(jì)和Thread-local相關(guān)的最佳實(shí)踐

要獲取更多Jerry的原創(chuàng)文章，請關(guān)注公眾號(hào)"汪子熙":