一個 API 應該容易學習和使用，且不易被誤用。它還應該隨著時間而發展，優秀的設計需要預見并適應這種變化。

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

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

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

Bloch 進一步指出，以 API 設計為思考核心，能顯著提高編寫程序的質量。

即使你作為一個程序員并不直接參與面向公眾的 API 開發，實際上你也在持續地創建 API。優秀的編程應該是模塊化的，模塊間的邊界自就是 API。同樣，如果你參與的是一個現代化的、分布式的、基于微服務架構的系統，那么服務間的邊界也構成了 API，只是架構有所不同。

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

1、名字至關重要

從宏觀角度來看，API 應該易于學習和使用，同時難以被誤用。它還需要隨著時間的發展而進化，而一個優秀的設計會將此考慮在內。

命名的方式極其重要，因為 API 在實質上是一種需要用戶學習的簡約語言。

「真正合適的命名可以解決問題并避免誤解，因為恰當的命名能夠非常明確地表明事物的本質?！筍oftIron 首席科學家 Harry Richardson 在接受 The New Stack 采訪時表示。

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

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

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

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

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

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

比如，一些大型企業會把高級技術寫作人員的職責擴展到幫助工程團隊統一命名方法、屬性和字段。

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

同時，雖然所有 API 都需要恰當的命名，但這些命名本身是特定于領域的；比如，為量化分析師編寫的 API 與為零售商編寫的 API 使用的語言會有很大不同。理想情況下，選用的術語應與企業已經使用并至少理解的術語匹配。

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

「QA 團隊成員與開發者對于你的 API 應如何運作會有不同的看法，」他說?！肝医洺Ｒ姷介_發者在沒有詢問誰會使用它的情況下設計 API，結果暴露了內部的領域模型?！?/span>

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

「如果你能簡化復雜事物，你就有可能顛覆人們的世界觀，隨著系統的演進，通常會出現很好的機會」Bryant說。

2、最小意外原則

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

API 應遵循最小意外原則。這一原則部分通過對稱性實現；比如說，如果你需要添加和刪除方法，這些操作應該在適當的地方被一致地實施。

一個優秀的 API 應該僅包含少數幾個概念；在學習它時，不應被迫學習太多內容。這并不特指方法、類或參數的數量，而是指 API 所涵蓋的概念范圍。理想情況下，一個 API 應該只專注于完成一個任務。

也最好避免無謂地添加任何元素。「不確定時就不要添加，」Bloch 這樣建議。你通?？梢栽谛枰獣r向 API 中添加某些內容，但一旦 API 被公開，就無法再移除其中的任何部分。

如之前所述，你的 API 需要隨時間發展，因此設計的一個關鍵方面是，在后續過程中能夠進行更改而不破壞整體結構。

「歸根到底，關鍵在于 API 應該反映現實，」Richardson表示?！咐?，如果一個人可以有多個地址或電話號碼，即便你目前只關注一個，也不應該僅允許存在一個地址。忽略現實最終總會帶來問題。」

3、API 的粘性

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

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

第二個問題涉及到封裝和實現細節的泄露。

「一旦實現細節泄露，你就無法更改它，」Richardson表示。「因此，你需要考慮，這里進行的操作是什么？這個數據結構的真實含義是什么？」

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

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

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

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

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

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

Richardson 強調。

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

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

「這些代碼不是無用功，」Bloch強調，「因為它不僅幫助你打造出更優秀的產品，還提供了一套可供其他程序員學習的范例。」

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