好的API都有哪些特點？你能做到幾點

作者丨 Erik Dietrich

譯者丨黑色巧克力

好的API是怎樣的，應該具備哪些特點，作者對此進行了詳細說明，並把API比作產品，主張編寫API時從用戶的角度換位思考。

如果用戶通過他們自己的代碼與你的代碼進行交互，那麼你將需要構建一個API。因此，理解好的API特性是至關重要的。那麼什麼是好的API呢?

「API」一詞似乎是對軟體開發人員的一種Rorschach Test。Web開發人員將API視為REST端點和wsdl。相比之下，桌面開發人員可能認為API是由來自其他組織的開發人員編寫的「代碼庫」。人們編寫像驅動程序這樣的低級代碼是為了提供操作系統調用的入口。

API提供了一種更通用的思維方式，我個人喜歡下面「技術術語」的定義。

API是一組命令、函數、協議和對象，程序員可以用它們來開發軟體或與外部系統進行交互。它為開發人員提供了執行通用操作的標準命令，這樣他們就不必從頭開始編寫代碼了。

API定義了其他程序員如何與軟體進行交互。因此，我提到的每一角色都有自己的正確答案，但只是一小部分。當你寫代碼的時候，想想調用這段代碼的用戶。如果該用戶想通過自己的代碼與你的代碼進行交互，那麼你將需要構建一個API。這方便於你公司的其他開發人員，甚至你的團隊使用你的代碼。

所以了解好的API的特性對我們至關重要。它會讓其他人在你的工作上有所不同。而且老實說，會帶來一定程度的職業自豪感。那麼什麼是好的API呢？讓我們看看一些好的API的特性。

簡單

首先簡單是最重要的。程序員傾向於解決複雜的問題，這使得我們很容易地讓這些複雜性影響到編寫的用戶API。保持簡單就需要大量工作，有時還會帶來嚴重的挑戰。

我們想要幫助的意願一定程度上增加了困難。通常，程序員想要提供幾種不同的方法來做一些事情。「也許他們想通過構造函數傳遞這些依賴關係。但是如果他們更喜歡使用setter呢?我們應該讓兩者都存在。」通向複雜性的道路就是這樣良好的意願鋪好的。

即使你認為它可能會有所幫助，也要努力去增加不必要的複雜性。好的api表現出簡單性，而且要保持這種簡單性需要付出很大的努力。

提供有用的抽象

接下來，考慮抽象的概念。當你成功地從用戶的API中隱藏細節只留下要點時，你就提供了抽象。

這個世界充滿了抽象的例子。設備驅動程序抽象處理供應商硬體的細節。線程模型提供了一種抽象，用於處理在OS級別上調度執行。操作系統本身為核心計算機硬體的不同提供了一個抽象概念。甚至你的編程語言也會抽象出編寫機器代碼的細節。

好的代碼提供了抽象，API也不例外。你的API應該隱藏它對用戶的詳細信息，同時使其對用戶有用。如果你的用戶需要深入代碼或執行來理解，你就提供了一個很差的抽象。

可發現的

簡單和好的抽象會讓你取得不錯的成績。但是，當你寫出一個「可發現」的API時，你將走的更遠。這與一個新手在使用你的代碼時的效率有很大的關係。

我將選用一個非代碼示例作有幫助的同類型比較。從用戶體驗角度想想看，最初的iPhone革命性的是什麼。它有一個屏幕和一個按鈕。它的應用程序把東西掛在屏幕的一邊，讓你發現可以通過左右滑動來提高你的使用頻率。與之前的設備不同，這款可發現的設備讓即使是最不聰明的用戶也能快速的進行操作。

讓你的API爭取做到這一點。要知道，你的用戶在拿起手冊或打電話詢問之前，他們會進行測試和實驗。相應的計劃和設計，包括文檔和示例，以及自我描述訪問點會讓API具備可發現性。另外使用一個名為GetLastNameFromOrder(CustomerOrder orderToQuery)的方法可以幫助你達到預期目的。

一致和對稱

假如你已經偏離了先前的考慮，那麼請檢查你的API以保持一致性和對稱性。一致性相對容易理解。有時候不要稱他們為「用戶」或「客戶」，用相同的方式命名相同的東西，保持一個共同的風格。從而讓你的API是可預測的。

對稱性是一個稍微有些微妙的考慮。當我談到對稱時，指的是一種以用戶期望的方式關閉開放循環的偏好。例如，如果你有一個用於文件訪問的API，它允許你調用Open(string文件名)，那麼你也應該提供一個Close(string文件名)方法。打開和關閉具有相反的含義，因此，提供兩種功能都可以作為操作的關注點來創建對稱。調用Close方法是「銷毀」，而如果沒有關閉方法，會造成很大的混亂。

在API中，你可以通過對向用戶公開的內容運用批判的眼光來實現這一特性。仔細閱讀校對者的方法，檢查一致性和對稱性，然後根據需要重命名和修改。

遵循最不驚奇的原則

作為最後的考慮，我想給大家介紹一個聰明的「最小驚奇原則」。這表示「一個系統應該以與該組件的用戶可能期望的行為一致的方式運行。也就是說，用戶不應該對它的行為感到驚訝。」更坦率地說，不要編寫API來讓你的用戶大吃一驚。

我上面關於對稱的例子也可以被認為違反了這一原則。但是讓我們稍微改變一下，讓它更明顯地說明這個原則是什麼意思。假設你的文件API有一個開放的(字元串文件名)方法，然後它要求你通過調用Open()來關閉文件，而且沒有參數。而無論何時你調用Close()，因為某些原因它都會發送一封電子郵件給一個叫Bill Smith的人。如果對這個過程做出反應，你就會得到一個「令人驚訝」的因素。

好的API並沒有導致用戶抓狂的屬性，「但是這沒有任何意義！」或者「我怎麼知道這一點?！」向用戶提供一個與它所宣稱的功能無關的API，我想沒有什麼比這更快捷的方式來失去用戶的信任了。

把API看作一種產品

簡單、有用、可發現、一致、可預測，所有這些不僅描述了良好的API，還描述了良好的產品。這不是偶然的，當你編寫API時，你將創建一個產品。不管你是否真的這樣想，不管你是否真的把產品賣了，你手上都有一個別人想要用的產品。

作為開發人員，我們很容易忽視這一點。根據知識的偏差，假設我們的API用戶是程序員，他們知道我們所知道的，理解我們所理解的，但我們並不認為他們是最終用戶或客戶。

要克服這種偏差，換位思考是設計好的API的關鍵思想。所以當你編寫下一個API時，把自己放在客戶的角度，想像你想要的是什麼。

點擊展開全文

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！