如今，能幫助開發人員設計API的工具、技術和平臺可謂種類繁多。盡管資源豐富，但API設計中仍然存在著一大難題：如何為API命名。這事聽起來簡單，但命名本身也需要一整套可持續且穩定可靠的設計流程，用以定義API的識別、分類與命名原則。總之，這事可絕不像很多人想象中那么輕松。

在《API設計模式》一書中，作者兼谷歌軟件工程師JJ Geewax把命名稱為API開發者最需要學習和掌握的眾多關鍵設計因素之一。合理的API命名約定不僅能改善API的可訪問性和用戶友好度，同時也有助于預防很多令人頭痛的API可用性問題。

名稱里的玄機

Geewax提到，API的名稱之所以如此重要，是因為API的功能往往取決于自身跟用戶的交互能力。用戶經常會通過API名稱來快速判斷訪問時將要接收、查看或操作的信息類型。此外，這些名稱還能指示出技術組合當中的哪些API彼此直接相關，或者在設計上負責處理哪些請求類型。

在書中第三章部分，Geewax討論了API命名方法的重要意義：

對于傳統編譯代碼，我們的函數和變量名稱只會影響到有權訪問源代碼的人。而經過編譯（最小化）和部署，這些名稱往往徹底消失。而在設計和構建API時，名稱的選擇則更加重要，因為它們負責代表并描述所有API用戶將要看到并進行交互的內容。

Geewax還強調，最好能在開發早期就確定API的命名模式，甚至可以考慮把命名作為開發的第一步。開發者應該為API命名實踐設定好期望，而具體名稱的選擇將最終影響到API組合的管理方式。例如，特定API所對應的特定名稱將影響到開發者在后續版本更新、或者出現新需求時，新增API所能使用的具體名稱。API組合規模越大，開發者就越難在不影響原有體系的前提下更改名稱模式。

API名稱：什么是好，什么是壞

Geewax在《API設計模式》中提出的命名實踐，基本上圍繞著同一個中心主題：API名稱是分好壞的。好的API名稱既要降低冗余，又應該最大限度減少用戶的理解難度。而壞名稱也可能誤導用戶，致使其理解錯亂、找不到自己最需要的API。在極端案例中，差勁的名稱甚至會引發冗余構建，白白浪費掉寶貴的應用程序資源、增加不必要的開發成本。

Geewax在書中以存儲用戶賬戶偏好項的API為例，提到如果開發者只是簡單把該API命名為API Preferences，那么用戶其實很難結合上下文理解這個API到底是什么作用。在這種情況下，UserPreferences之類的名稱明顯更合適，能保證用戶準確理解自己要處理的是什么。

另一方面，名稱太過具體并不是好事。假設開發者把這個用戶偏好項API命名成了SingleUserAccountPreferences，那使用者可能會懷疑該API到底是存儲著很多用戶的個人偏好、還是只存儲單一個人用戶的偏好。如果碰巧認定為后一種解釋，開發團隊甚至有可能為每個單獨的賬戶分別構建API。所以說，UserPreferences才是最佳選擇，詳略得當而且清晰易懂。

API名稱特征

在命名API的時候，開發者其實也可以靈活發揮，畢竟命名約定并不像程序代碼那樣具有嚴格的語法和結構要求。但是，靈活性可不代表什么東西都能拿來當名稱。

如果同樣有多種方式來表達同一事物，我們往往傾向于把這些表達混合使用，而這最終會導致命名規則變得復雜莫測，也讓使用者難以區分不同API之間的聯系和不同。為此，我們必須控制住靈活表達的“誘惑”，強加給自己一些命名規則，避免破壞API名稱的良好可預測性。

當然，什么是清晰、什么是簡單、如何尋求二者的平衡，具體還是要取決于項目特性。想找到百試百靈的通行辦法幾乎不太可能。作為指導，Geewax結合API設計原則，提出了API名稱中所應體現的三大特征：

表達力：意味著API名稱應該清晰傳達它所代表的功能、資源、消息、字段、屬性或值的類型；

簡單性：要求名稱除表達力之外，還應在每個具體部分都提供合理價值；

可預測性：意味著API名稱應該易于理解，且遵循明確的命名模式。

那么，開發者該如何確保API名稱滿足這三大條件呢？Geewax的答案，是為API命名確定四條通行的執行原則。

第一，優先使用美式英語。雖然肯定會有例外，但API名稱最好使用美式英語，這也是編程世界中最具全球認可度的語言。如果必要，最好能始終提供本地化說明文檔。

第二，注意使用正確的語法。雖然簡略化的語法干練誘人，但在API名稱中最好堅持使用正確的語法規則。比如，使用正確的拼寫方式，關注名詞單復數的適當使用。這樣既有助于準確表達API作用，也能降低用戶混淆的風險。

第三，句法同樣重要。句法規定的是API名稱中的單詞排列順序。在大多數開發場景下，句法應遵循三大標準格式之一：camel、snake和kabab。

最后，確保包含上下文。理想條件下，API名稱應該提供一些與框架或程序類型相關的提示。如果API名稱在不同場景下可能代表不同含義，最好能添加上下文以消除產生誤解的可能性。