一個 API 應(yīng)該容易學(xué)習(xí)和使用，且不易被誤用。它還應(yīng)該隨著時間而發(fā)展，優(yōu)秀的設(shè)計需要預(yù)見并適應(yīng)這種變化。

Joshua Bloch 曾在 Sun 擔(dān)任杰出工程師，之后加入谷歌成為首席 Java 架構(gòu)師。他主導(dǎo)了 Java 平臺上的很多功能，包括 Java Collections 框架，java.math 包，assert 機(jī)制等。他也是 Effective Java 的作者。

在谷歌 2007 年的一場重要演講中，軟件工程師兼技術(shù)作家 Joshua Bloch 強調(diào)了 API 是一種極其重要的商業(yè)資產(chǎn)。他指出，這主要是因為如果 API 對外開放，客戶可能會選擇在上面進(jìn)行大量投資，從而很難改變使用習(xí)慣。

Bloch 還警告說，設(shè)計糟糕的 API 可能會導(dǎo)致無休止的客戶支持電話，極大地阻礙公司的發(fā)展。

Bloch 進(jìn)一步指出，以 API 設(shè)計為思考核心，能顯著提高編寫程序的質(zhì)量。

即使你作為一個程序員并不直接參與面向公眾的 API 開發(fā)，實際上你也在持續(xù)地創(chuàng)建 API。優(yōu)秀的編程應(yīng)該是模塊化的，模塊間的邊界自就是 API。同樣，如果你參與的是一個現(xiàn)代化的、分布式的、基于微服務(wù)架構(gòu)的系統(tǒng)，那么服務(wù)間的邊界也構(gòu)成了 API，只是架構(gòu)有所不同。

盡管如此，API 設(shè)計仍然是許多程序員面臨的一個挑戰(zhàn)。那么，一個好的 API 有哪些特點呢？

1、名字至關(guān)重要

從宏觀角度來看，API 應(yīng)該易于學(xué)習(xí)和使用，同時難以被誤用。它還需要隨著時間的發(fā)展而進(jìn)化，而一個優(yōu)秀的設(shè)計會將此考慮在內(nèi)。

命名的方式極其重要，因為 API 在實質(zhì)上是一種需要用戶學(xué)習(xí)的簡約語言。

「真正合適的命名可以解決問題并避免誤解，因為恰當(dāng)?shù)拿軌蚍浅Ｃ鞔_地表明事物的本質(zhì)?！筍oftIron 首席科學(xué)家 Harry Richardson 在接受 The New Stack 采訪時表示。

Richardson 特別指出，對于開發(fā)者來說，命名塑造了我們的思維模型。

「改變一個已經(jīng)形成的思維模型是相當(dāng)困難的工作，這不一定是在代碼方面，而是關(guān)于我們思考問題方式的方面?！?/span>

因此，投入時間去精心挑選一個能夠精確描述 API 功能的名稱是非常值得的。

作為一個作家的基本工具 —— 字典和詞典 —— 在 API 命名過程中也能提供幫助。如果你發(fā)現(xiàn)某個名字特別難以確定，這可能意味著它嘗試同時承擔(dān)太多的職責(zé)。就像需要將過于復(fù)雜的句子分割成更簡單的句子一樣，當(dāng)一個模塊過于復(fù)雜時，也應(yīng)該考慮將其拆分。

要避免使用讓人費解的縮寫，并且注意保持命名的一致性。比如，不應(yīng)該同時使用 getBasicSalary() 和 getBaseSalary() 這樣意義相同但命名不一的方法 —— 如果你的 API 中既有 remove() 又有 delete() 方法，使用者能夠清楚地知道它們之間的區(qū)別嗎？

使用的語言需要與組織或供應(yīng)商公開的其他 API 保持一致性。這種對一致性的追求意味著，實施一定程度的集中化管理會很有幫助。

比如，一些大型企業(yè)會把高級技術(shù)寫作人員的職責(zé)擴(kuò)展到幫助工程團(tuán)隊統(tǒng)一命名方法、屬性和字段。

如果你正在開發(fā) REST 風(fēng)格的系統(tǒng)，獨立咨詢師兼《掌握 API 架構(gòu)》一書的合作者 Daniel Bryant 建議參考已有的 API 指南集，這有助于在 API 的行為上實現(xiàn)一致性。對于基于 HTTP 的 API，他推薦考慮使用 OpenAPI，還有其他包括 Atlassian、Google 和 Microsoft 在內(nèi)的指南。

同時，雖然所有 API 都需要恰當(dāng)?shù)拿@些命名本身是特定于領(lǐng)域的；比如，為量化分析師編寫的 API 與為零售商編寫的 API 使用的語言會有很大不同。理想情況下，選用的術(shù)語應(yīng)與企業(yè)已經(jīng)使用并至少理解的術(shù)語匹配。

為此，Bryant 在對 The New Stack 的講述中提到，最佳做法是進(jìn)行用戶研究，確保覆蓋所有潛在的 API 使用群體。

「QA 團(tuán)隊成員與開發(fā)者對于你的 API 應(yīng)如何運作會有不同的看法，」他說。「我經(jīng)常見到開發(fā)者在沒有詢問誰會使用它的情況下設(shè)計 API，結(jié)果暴露了內(nèi)部的領(lǐng)域模型。」

他推薦從「待完成的工作」（Jobs-to-be-Done）的角度來考慮，比如：你的關(guān)鍵任務(wù)是什么？你的工作流是怎樣的？你是如何處理它的？你希望如何處理它？最后一個問題至關(guān)重要，因為圍繞已建立的流程可能會形成慣性。

「如果你能簡化復(fù)雜事物，你就有可能顛覆人們的世界觀，隨著系統(tǒng)的演進(jìn)，通常會出現(xiàn)很好的機(jī)會」Bryant說。

2、最小意外原則

你的 API 也應(yīng)該符合其所用編程語言的慣常用法，并尊重該語言的工作機(jī)制。例如，如果 API 要和 Java 配合使用，就應(yīng)該通過拋出異常來處理錯誤，而不是像在 C 語言中那樣返回錯誤代碼。

API 應(yīng)遵循最小意外原則。這一原則部分通過對稱性實現(xiàn)；比如說，如果你需要添加和刪除方法，這些操作應(yīng)該在適當(dāng)?shù)牡胤奖灰恢碌貙嵤?/span>

一個優(yōu)秀的 API 應(yīng)該僅包含少數(shù)幾個概念；在學(xué)習(xí)它時，不應(yīng)被迫學(xué)習(xí)太多內(nèi)容。這并不特指方法、類或參數(shù)的數(shù)量，而是指 API 所涵蓋的概念范圍。理想情況下，一個 API 應(yīng)該只專注于完成一個任務(wù)。

也最好避免無謂地添加任何元素?！覆淮_定時就不要添加，」Bloch 這樣建議。你通常可以在需要時向 API 中添加某些內(nèi)容，但一旦 API 被公開，就無法再移除其中的任何部分。

如之前所述，你的 API 需要隨時間發(fā)展，因此設(shè)計的一個關(guān)鍵方面是，在后續(xù)過程中能夠進(jìn)行更改而不破壞整體結(jié)構(gòu)。

「歸根到底，關(guān)鍵在于 API 應(yīng)該反映現(xiàn)實，」Richardson表示?！咐纾绻粋€人可以有多個地址或電話號碼，即便你目前只關(guān)注一個，也不應(yīng)該僅允許存在一個地址。忽略現(xiàn)實最終總會帶來問題?！?/span>

3、API 的粘性

Richardson 指出，僅實施你當(dāng)前需要的 API 的一部分是一個常見的錯誤模式。這種做法的風(fēng)險在于，你可能沒有徹底思考 API 的設(shè)計，最終導(dǎo)致在其他場景下不可用的結(jié)果。

「API 設(shè)計需要比任何其他事情投入更多的思考，」Richardson 說，「因為一旦建成，你就無法再對其進(jìn)行更改?！?/span>

第二個問題涉及到封裝和實現(xiàn)細(xì)節(jié)的泄露。

「一旦實現(xiàn)細(xì)節(jié)泄露，你就無法更改它，」Richardson表示。「因此，你需要考慮，這里進(jìn)行的操作是什么？這個數(shù)據(jù)結(jié)構(gòu)的真實含義是什么？」

錯誤處理通常是被忽略的一個領(lǐng)域。比如，如果你使用數(shù)據(jù)庫作為后端存儲，就不應(yīng)該讓 SQL 錯誤直接暴露出來，因為如果你以后想更改存儲機(jī)制，這樣做就會遇到障礙。

就像軟件開發(fā)的任何其他方面一樣，認(rèn)為你可以孤立地把自己鎖在一個房間里獨立完成 API 的開發(fā)是一個錯誤。這樣做，你可能會過于堅持自己的設(shè)計，即便設(shè)計存在問題。最好是像對待任何其他系統(tǒng)一樣，頻繁地與合作方一起測試你的想法。

在開始編碼 API 之前，編寫一個簡短的規(guī)格說明書，向合作方展示它將做什么以及如何工作是個不錯的主意。規(guī)格說明書保持簡短，這樣可以增加被閱讀的可能性，并防止你一開始就過于投入你的方案。如果你花費幾個月時間編寫了一個 100 頁的規(guī)格說明書，你就很難承認(rèn)它可能并不那么優(yōu)秀。

文檔是被極度低估的一方面，這不僅適用于 API 設(shè)計，在整個計算機(jī)科學(xué)領(lǐng)域都是如此。技術(shù)文檔編寫者經(jīng)常被低估和低薪，而文檔最多被當(dāng)作事后的補充，這種情況常被「代碼即文檔」這一危險的觀點所體現(xiàn)。

雖然你希望你的 API 易于理解和學(xué)習(xí)，但它的文檔仍極為重要。它應(yīng)當(dāng)是完整而全面的，至少包含每個方法的用途、每個字段的作用以及可能的錯誤條件。

「你希望它能列出所有可能返回的錯誤代碼及其對應(yīng)的情況」

Richardson 強調(diào)。

投入時間來打磨和修正文檔，避免諸如使用不容易理解的縮寫這樣的常見錯誤。

在開發(fā)過程中，繼續(xù)根據(jù) API 編寫示例代碼。Bloch 提到，許多開發(fā)者在開發(fā)過程往往半途而廢，但是如果在整個實施過程中持續(xù)對 API 進(jìn)行編碼，你將能夠真實地感受到它的工作時機(jī)和方式。

「這些代碼不是無用功，」Bloch強調(diào)，「因為它不僅幫助你打造出更優(yōu)秀的產(chǎn)品，還提供了一套可供其他程序員學(xué)習(xí)的范例?！?/span>

這些示例極為關(guān)鍵，因為它們將被其他開發(fā)者不斷地復(fù)制使用，從而根本性地影響 API 的使用方式。