好的API是怎樣的，應(yīng)該具備哪些特點(diǎn)，作者對此進(jìn)行了詳細(xì)說明，并把API比作產(chǎn)品，主張編寫API時從用戶的角度換位思考。

　　如果用戶通過他們自己的代碼與你的代碼進(jìn)行交互，那么你將需要構(gòu)建一個API。因此，理解好的API特性是至關(guān)重要的。那么什么是好的API呢？

　　“API”一詞似乎是對軟件開發(fā)人員的一種Rorschach Test。Web開發(fā)人員將API視為REST端點(diǎn)和wsdl。相比之下，桌面開發(fā)人員可能認(rèn)為API是由來自其他組織的開發(fā)人員編寫的“代碼庫”。人們編寫像驅(qū)動程序這樣的低級代碼是為了提供操作系統(tǒng)調(diào)用的入口。

　　API提供了一種更通用的思維方式，我個人喜歡下面“技術(shù)術(shù)語”的定義。

　　API是一組命令、函數(shù)、協(xié)議和對象，程序員可以用它們來開發(fā)軟件或與外部系統(tǒng)進(jìn)行交互。它為開發(fā)人員提供了執(zhí)行通用操作的標(biāo)準(zhǔn)命令，這樣他們就不必從頭開始編寫代碼了。

　　API定義了其他程序員如何與軟件進(jìn)行交互。因此，我提到的每一角色都有自己的正確答案，但只是一小部分。當(dāng)你寫代碼的時候，想想調(diào)用這段代碼的用戶。如果該用戶想通過自己的代碼與你的代碼進(jìn)行交互，那么你將需要構(gòu)建一個API。這方便于你公司的其他開發(fā)人員，甚至你的團(tuán)隊(duì)使用你的代碼。

　　所以了解好的API的特性對我們至關(guān)重要。它會讓其他人在你的工作上有所不同。而且老實(shí)說，會帶來一定程度的職業(yè)自豪感。那么什么是好的API呢？讓我們看看一些好的API的特性。

　　簡單

　　首先簡單是最重要的。程序員傾向于解決復(fù)雜的問題，這使得我們很容易地讓這些復(fù)雜性影響到編寫的用戶API。保持簡單就需要大量工作，有時還會帶來嚴(yán)重的挑戰(zhàn)。

　　我們想要幫助的意愿一定程度上增加了困難。通常，程序員想要提供幾種不同的方法來做一些事情?！耙苍S他們想通過構(gòu)造函數(shù)傳遞這些依賴關(guān)系。但是如果他們更喜歡使用setter呢？我們應(yīng)該讓兩者都存在?！蓖ㄏ驈?fù)雜性的道路就是這樣良好的意愿鋪好的。

　　即使你認(rèn)為它可能會有所幫助，也要努力去增加不必要的復(fù)雜性。好的api表現(xiàn)出簡單性，而且要保持這種簡單性需要付出很大的努力。

　　提供有用的抽象

　　接下來，考慮抽象的概念。當(dāng)你成功地從用戶的API中隱藏細(xì)節(jié)只留下要點(diǎn)時，你就提供了抽象。

　　這個世界充滿了抽象的例子。設(shè)備驅(qū)動程序抽象處理供應(yīng)商硬件的細(xì)節(jié)。線程模型提供了一種抽象，用于處理在OS級別上調(diào)度執(zhí)行。操作系統(tǒng)本身為核心計(jì)算機(jī)硬件的不同提供了一個抽象概念。甚至你的編程語言也會抽象出編寫機(jī)器代碼的細(xì)節(jié)。

　　好的代碼提供了抽象，API也不例外。你的API應(yīng)該隱藏它對用戶的詳細(xì)信息，同時使其對用戶有用。如果你的用戶需要深入代碼或執(zhí)行來理解，你就提供了一個很差的抽象。

　　可發(fā)現(xiàn)的

　　簡單和好的抽象會讓你取得不錯的成績。但是，當(dāng)你寫出一個“可發(fā)現(xiàn)”的API時，你將走的更遠(yuǎn)。這與一個新手在使用你的代碼時的效率有很大的關(guān)系。

　　我將選用一個非代碼示例作有幫助的同類型比較。從用戶體驗(yàn)角度想想看，最初的iPhone革命性的是什么。它有一個屏幕和一個按鈕。它的應(yīng)用程序把東西掛在屏幕的一邊，讓你發(fā)現(xiàn)可以通過左右滑動來提高你的使用頻率。與之前的設(shè)備不同，這款可發(fā)現(xiàn)的設(shè)備讓即使是最不聰明的用戶也能快速的進(jìn)行操作。

　　讓你的API爭取做到這一點(diǎn)。要知道，你的用戶在拿起手冊或打電話詢問之前，他們會進(jìn)行測試和實(shí)驗(yàn)。相應(yīng)的計(jì)劃和設(shè)計(jì)，包括文檔和示例，以及自我描述訪問點(diǎn)會讓API具備可發(fā)現(xiàn)性。另外使用一個名為GetLastNameFromOrder（CustomerOrder orderToQuery）的方法可以幫助你達(dá)到預(yù)期目的。

　　一致和對稱

　　假如你已經(jīng)偏離了先前的考慮，那么請檢查你的API以保持一致性和對稱性。一致性相對容易理解。有時候不要稱他們?yōu)椤坝脩簟被颉翱蛻簟保孟嗤姆绞矫嗤臇|西，保持一個共同的風(fēng)格。從而讓你的API是可預(yù)測的。

　　對稱性是一個稍微有些微妙的考慮。當(dāng)我談到對稱時，指的是一種以用戶期望的方式關(guān)閉開放循環(huán)的偏好。例如，如果你有一個用于文件訪問的API，它允許你調(diào)用Open（string文件名），那么你也應(yīng)該提供一個Close（string文件名）方法。打開和關(guān)閉具有相反的含義，因此，提供兩種功能都可以作為操作的關(guān)注點(diǎn)來創(chuàng)建對稱。調(diào)用Close方法是“銷毀”，而如果沒有關(guān)閉方法，會造成很大的混亂。

　　在API中，你可以通過對向用戶公開的內(nèi)容運(yùn)用批判的眼光來實(shí)現(xiàn)這一特性。仔細(xì)閱讀校對者的方法，檢查一致性和對稱性，然后根據(jù)需要重命名和修改。

　　遵循最不驚奇的原則

　　作為最后的考慮，我想給大家介紹一個聰明的“最小驚奇原則”。這表示“一個系統(tǒng)應(yīng)該以與該組件的用戶可能期望的行為一致的方式運(yùn)行。也就是說，用戶不應(yīng)該對它的行為感到驚訝?！备孤实卣f，不要編寫API來讓你的用戶大吃一驚。

　　我上面關(guān)于對稱的例子也可以被認(rèn)為違反了這一原則。但是讓我們稍微改變一下，讓它更明顯地說明這個原則是什么意思。假設(shè)你的文件API有一個開放的（字符串文件名）方法，然后它要求你通過調(diào)用Open（）來關(guān)閉文件，而且沒有參數(shù)。而無論何時你調(diào)用Close（），因?yàn)槟承┰蛩紩l(fā)送一封電子郵件給一個叫Bill Smith的人。如果對這個過程做出反應(yīng)，你就會得到一個“令人驚訝”的因素。

　　好的API并沒有導(dǎo)致用戶抓狂的屬性，“但是這沒有任何意義！”或者“我怎么知道這一點(diǎn)？！”向用戶提供一個與它所宣稱的功能無關(guān)的API，我想沒有什么比這更快捷的方式來失去用戶的信任了。

　　把API看作一種產(chǎn)品

　　簡單、有用、可發(fā)現(xiàn)、一致、可預(yù)測，所有這些不僅描述了良好的API，還描述了良好的產(chǎn)品。這不是偶然的，當(dāng)你編寫API時，你將創(chuàng)建一個產(chǎn)品。不管你是否真的這樣想，不管你是否真的把產(chǎn)品賣了，你手上都有一個別人想要用的產(chǎn)品。

　　作為開發(fā)人員，我們很容易忽視這一點(diǎn)。根據(jù)知識的偏差，假設(shè)我們的API用戶是程序員，他們知道我們所知道的，理解我們所理解的，但我們并不認(rèn)為他們是最終用戶或客戶。

　　要克服這種偏差，換位思考是設(shè)計(jì)好的API的關(guān)鍵思想。所以當(dāng)你編寫下一個API時，把自己放在客戶的角度，想象你想要的是什么。

相關(guān)電子資料下載

• Pipeline中throwIt的用法 62
• Python怎么使用漫威庫 62
• 如何實(shí)現(xiàn)RTOS、中間件和芯片廠商API的跟蹤可觀察性？ 178
• 深入探討Granite Rapids和Sierra Forest處理器架構(gòu)技術(shù) 20
• 基于OpenVINO Python API部署RT-DETR模型 107
• MaaS，云廠商在打一場“翻身仗” 525
• Nginx常用配置與命令 20
• 愛立信消費(fèi)者實(shí)驗(yàn)室報(bào)告：差異化的5G連接為運(yùn)營商帶來商機(jī) 230
• 緩存的好處和類型 84
• 工程師分享的7個編程習(xí)慣 103