取名的藝術(shù)：為什么說API命名約定很重要？
如今，能幫助開發(fā)人員設計API的工具、技術(shù)和平臺可謂種類繁多。盡管資源豐富，但API設計中仍然存在著一大難題：如何為API命名。這事聽起來簡單，但命名本身也需要一整套可持續(xù)且穩(wěn)定可靠的設計流程，用以定義API的識別、分類與命名原則�？傊�，這事可絕不像很多人想象中那么輕松。
在《API設計模式》一書中，作者兼谷歌軟件工程師JJ Geewax把命名稱為API開發(fā)者最需要學習和掌握的眾多關鍵設計因素之一。合理的API命名約定不僅能改善API的可訪問性和用戶友好度，同時也有助于預防很多令人頭痛的API可用性問題。
名稱里的玄機
Geewax提到，API的名稱之所以如此重要，是因為API的功能往往取決于自身跟用戶的交互能力。用戶經(jīng)常會通過API名稱來快速判斷訪問時將要接收、查看或操作的信息類型。此外，這些名稱還能指示出技術(shù)組合當中的哪些API彼此直接相關，或者在設計上負責處理哪些請求類型。
在書中第三章部分，Geewax討論了API命名方法的重要意義：
對于傳統(tǒng)編譯代碼，我們的函數(shù)和變量名稱只會影響到有權(quán)訪問源代碼的人。而經(jīng)過編譯（最小化）和部署，這些名稱往往徹底消失。而在設計和構(gòu)建API時，名稱的選擇則更加重要，因為它們負責代表并描述所有API用戶將要看到并進行交互的內(nèi)容。
Geewax還強調(diào)，最好能在開發(fā)早期就確定API的命名模式，甚至可以考慮把命名作為開發(fā)的第一步。開發(fā)者應該為API命名實踐設定好期望，而具體名稱的選擇將最終影響到API組合的管理方式。例如，特定API所對應的特定名稱將影響到開發(fā)者在后續(xù)版本更新、或者出現(xiàn)新需求時，新增API所能使用的具體名稱。API組合規(guī)模越大，開發(fā)者就越難在不影響原有體系的前提下更改名稱模式。
API名稱：什么是好，什么是壞
Geewax在《API設計模式》中提出的命名實踐，基本上圍繞著同一個中心主題：API名稱是分好壞的。好的API名稱既要降低冗余，又應該最大限度減少用戶的理解難度。而壞名稱也可能誤導用戶，致使其理解錯亂、找不到自己最需要的API。在極端案例中，差勁的名稱甚至會引發(fā)冗余構(gòu)建，白白浪費掉寶貴的應用程序資源、增加不必要的開發(fā)成本。
Geewax在書中以存儲用戶賬戶偏好項的API為例，提到如果開發(fā)者只是簡單把該API命名為API Preferences，那么用戶其實很難結(jié)合上下文理解這個API到底是什么作用。在這種情況下，UserPreferences之類的名稱明顯更合適，能保證用戶準確理解自己要處理的是什么。
另一方面，名稱太過具體并不是好事。假設開發(fā)者把這個用戶偏好項API命名成了SingleUserAccountPreferences，那使用者可能會懷疑該API到底是存儲著很多用戶的個人偏好、還是只存儲單一個人用戶的偏好。如果碰巧認定為后一種解釋，開發(fā)團隊甚至有可能為每個單獨的賬戶分別構(gòu)建API。所以說，UserPreferences才是最佳選擇，詳略得當而且清晰易懂。
API名稱特征
在命名API的時候，開發(fā)者其實也可以靈活發(fā)揮，畢竟命名約定并不像程序代碼那樣具有嚴格的語法和結(jié)構(gòu)要求。但是，靈活性可不代表什么東西都能拿來當名稱。
如果同樣有多種方式來表達同一事物，我們往往傾向于把這些表達混合使用，而這最終會導致命名規(guī)則變得復雜莫測，也讓使用者難以區(qū)分不同API之間的聯(lián)系和不同。為此，我們必須控制住靈活表達的“誘惑”，強加給自己一些命名規(guī)則，避免破壞API名稱的良好可預測性。
當然，什么是清晰、什么是簡單、如何尋求二者的平衡，具體還是要取決于項目特性。想找到百試百靈的通行辦法幾乎不太可能。作為指導，Geewax結(jié)合API設計原則，提出了API名稱中所應體現(xiàn)的三大特征：
表達力：意味著API名稱應該清晰傳達它所代表的功能、資源、消息、字段、屬性或值的類型；
簡單性：要求名稱除表達力之外，還應在每個具體部分都提供合理價值；
可預測性：意味著API名稱應該易于理解，且遵循明確的命名模式。
那么，開發(fā)者該如何確保API名稱滿足這三大條件呢？Geewax的答案，是為API命名確定四條通行的執(zhí)行原則。
第一，優(yōu)先使用美式英語。雖然肯定會有例外，但API名稱最好使用美式英語，這也是編程世界中最具全球認可度的語言。如果必要，最好能始終提供本地化說明文檔。
第二，注意使用正確的語法。雖然簡略化的語法干練誘人，但在API名稱中最好堅持使用正確的語法規(guī)則。比如，使用正確的拼寫方式，關注名詞單復數(shù)的適當使用。這樣既有助于準確表達API作用，也能降低用戶混淆的風險。
第三，句法同樣重要。句法規(guī)定的是API名稱中的單詞排列順序。在大多數(shù)開發(fā)場景下，句法應遵循三大標準格式之一：camel、snake和kabab。
最后，確保包含上下文。理想條件下，API名稱應該提供一些與框架或程序類型相關的提示。如果API名稱在不同場景下可能代表不同含義，最好能添加上下文以消除產(chǎn)生誤解的可能性。
