如今，能幫助開(kāi)發(fā)人員設(shè)計(jì)API的工具、技術(shù)和平臺(tái)可謂種類(lèi)繁多。盡管資源豐富，但API設(shè)計(jì)中仍然存在著一大難題：如何為API命名。這事聽(tīng)起來(lái)簡(jiǎn)單，但命名本身也需要一整套可持續(xù)且穩(wěn)定可靠的設(shè)計(jì)流程，用以定義API的識(shí)別、分類(lèi)與命名原則?？傊?，這事可絕不像很多人想象中那么輕松。

在《API設(shè)計(jì)模式》一書(shū)中，作者兼谷歌軟件工程師JJ Geewax把命名稱(chēng)為API開(kāi)發(fā)者最需要學(xué)習(xí)和掌握的眾多關(guān)鍵設(shè)計(jì)因素之一。合理的API命名約定不僅能改善API的可訪問(wèn)性和用戶友好度，同時(shí)也有助于預(yù)防很多令人頭痛的API可用性問(wèn)題。

名稱(chēng)里的玄機(jī)

Geewax提到，API的名稱(chēng)之所以如此重要，是因?yàn)锳PI的功能往往取決于自身跟用戶的交互能力。用戶經(jīng)常會(huì)通過(guò)API名稱(chēng)來(lái)快速判斷訪問(wèn)時(shí)將要接收、查看或操作的信息類(lèi)型。此外，這些名稱(chēng)還能指示出技術(shù)組合當(dāng)中的哪些API彼此直接相關(guān)，或者在設(shè)計(jì)上負(fù)責(zé)處理哪些請(qǐng)求類(lèi)型。

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

對(duì)于傳統(tǒng)編譯代碼，我們的函數(shù)和變量名稱(chēng)只會(huì)影響到有權(quán)訪問(wèn)源代碼的人。而經(jīng)過(guò)編譯（最小化）和部署，這些名稱(chēng)往往徹底消失。而在設(shè)計(jì)和構(gòu)建API時(shí)，名稱(chēng)的選擇則更加重要，因?yàn)樗鼈冐?fù)責(zé)代表并描述所有API用戶將要看到并進(jìn)行交互的內(nèi)容。

Geewax還強(qiáng)調(diào)，最好能在開(kāi)發(fā)早期就確定API的命名模式，甚至可以考慮把命名作為開(kāi)發(fā)的第一步。開(kāi)發(fā)者應(yīng)該為API命名實(shí)踐設(shè)定好期望，而具體名稱(chēng)的選擇將最終影響到API組合的管理方式。例如，特定API所對(duì)應(yīng)的特定名稱(chēng)將影響到開(kāi)發(fā)者在后續(xù)版本更新、或者出現(xiàn)新需求時(shí)，新增API所能使用的具體名稱(chēng)。API組合規(guī)模越大，開(kāi)發(fā)者就越難在不影響原有體系的前提下更改名稱(chēng)模式。

API名稱(chēng)：什么是好，什么是壞

Geewax在《API設(shè)計(jì)模式》中提出的命名實(shí)踐，基本上圍繞著同一個(gè)中心主題：API名稱(chēng)是分好壞的。好的API名稱(chēng)既要降低冗余，又應(yīng)該最大限度減少用戶的理解難度。而壞名稱(chēng)也可能誤導(dǎo)用戶，致使其理解錯(cuò)亂、找不到自己最需要的API。在極端案例中，差勁的名稱(chēng)甚至?xí)l(fā)冗余構(gòu)建，白白浪費(fèi)掉寶貴的應(yīng)用程序資源、增加不必要的開(kāi)發(fā)成本。

Geewax在書(shū)中以存儲(chǔ)用戶賬戶偏好項(xiàng)的API為例，提到如果開(kāi)發(fā)者只是簡(jiǎn)單把該API命名為API Preferences，那么用戶其實(shí)很難結(jié)合上下文理解這個(gè)API到底是什么作用。在這種情況下，UserPreferences之類(lèi)的名稱(chēng)明顯更合適，能保證用戶準(zhǔn)確理解自己要處理的是什么。

另一方面，名稱(chēng)太過(guò)具體并不是好事。假設(shè)開(kāi)發(fā)者把這個(gè)用戶偏好項(xiàng)API命名成了SingleUserAccountPreferences，那使用者可能會(huì)懷疑該API到底是存儲(chǔ)著很多用戶的個(gè)人偏好、還是只存儲(chǔ)單一個(gè)人用戶的偏好。如果碰巧認(rèn)定為后一種解釋?zhuān)_(kāi)發(fā)團(tuán)隊(duì)甚至有可能為每個(gè)單獨(dú)的賬戶分別構(gòu)建API。所以說(shuō)，UserPreferences才是最佳選擇，詳略得當(dāng)而且清晰易懂。

API名稱(chēng)特征

在命名API的時(shí)候，開(kāi)發(fā)者其實(shí)也可以靈活發(fā)揮，畢竟命名約定并不像程序代碼那樣具有嚴(yán)格的語(yǔ)法和結(jié)構(gòu)要求。但是，靈活性可不代表什么東西都能拿來(lái)當(dāng)名稱(chēng)。

如果同樣有多種方式來(lái)表達(dá)同一事物，我們往往傾向于把這些表達(dá)混合使用，而這最終會(huì)導(dǎo)致命名規(guī)則變得復(fù)雜莫測(cè)，也讓使用者難以區(qū)分不同API之間的聯(lián)系和不同。為此，我們必須控制住靈活表達(dá)的“誘惑”，強(qiáng)加給自己一些命名規(guī)則，避免破壞API名稱(chēng)的良好可預(yù)測(cè)性。

當(dāng)然，什么是清晰、什么是簡(jiǎn)單、如何尋求二者的平衡，具體還是要取決于項(xiàng)目特性。想找到百試百靈的通行辦法幾乎不太可能。作為指導(dǎo)，Geewax結(jié)合API設(shè)計(jì)原則，提出了API名稱(chēng)中所應(yīng)體現(xiàn)的三大特征：

表達(dá)力：意味著API名稱(chēng)應(yīng)該清晰傳達(dá)它所代表的功能、資源、消息、字段、屬性或值的類(lèi)型；

簡(jiǎn)單性：要求名稱(chēng)除表達(dá)力之外，還應(yīng)在每個(gè)具體部分都提供合理價(jià)值；

可預(yù)測(cè)性：意味著API名稱(chēng)應(yīng)該易于理解，且遵循明確的命名模式。

那么，開(kāi)發(fā)者該如何確保API名稱(chēng)滿足這三大條件呢？Geewax的答案，是為API命名確定四條通行的執(zhí)行原則。

第一，優(yōu)先使用美式英語(yǔ)。雖然肯定會(huì)有例外，但API名稱(chēng)最好使用美式英語(yǔ)，這也是編程世界中最具全球認(rèn)可度的語(yǔ)言。如果必要，最好能始終提供本地化說(shuō)明文檔。

第二，注意使用正確的語(yǔ)法。雖然簡(jiǎn)略化的語(yǔ)法干練誘人，但在API名稱(chēng)中最好堅(jiān)持使用正確的語(yǔ)法規(guī)則。比如，使用正確的拼寫(xiě)方式，關(guān)注名詞單復(fù)數(shù)的適當(dāng)使用。這樣既有助于準(zhǔn)確表達(dá)API作用，也能降低用戶混淆的風(fēng)險(xiǎn)。

第三，句法同樣重要。句法規(guī)定的是API名稱(chēng)中的單詞排列順序。在大多數(shù)開(kāi)發(fā)場(chǎng)景下，句法應(yīng)遵循三大標(biāo)準(zhǔn)格式之一：camel、snake和kabab。

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