說實(shí)話，我非常希望自己能早點(diǎn)看到本篇文章，大學(xué)那個(gè)時(shí)候懵懵懂懂，跟著網(wǎng)上的免費(fèi)教程做了一個(gè)購(gòu)物商城就屁顛屁顛往簡(jiǎn)歷上寫。

至今我仍清晰地記得，那個(gè)電商教程是怎么定義接口的：

管它是增加、修改、刪除、帶參查詢，全是 POST 請(qǐng)求一把梭，比如下面這樣：

修改用戶的收貨地址

POST/xxx-mall/cart/update_address

現(xiàn)在看來，全部用 POST 請(qǐng)求估計(jì)是為了傳參方便吧。

那個(gè)時(shí)候自己也沒有一個(gè)API 接口需要設(shè)計(jì)的意識(shí)，跟學(xué)過類似教程的朋友應(yīng)該懂的，老師敲一行代碼學(xué)生跟著敲一行。如果沒人提這個(gè)事情，正式工作進(jìn)入團(tuán)隊(duì)后，是很容易出丑的......（作者親身經(jīng)歷，捂臉）

本文就不用 PPT 教案上的那種官方腔介紹 API 接口是個(gè)什么概念了，比較希望用一種聊天的方式和大家分享下現(xiàn)有的一丁丁和 API 相關(guān)的小心得，文章會(huì)分為五小塊：

初識(shí) API 接口

關(guān)于 API 限流

關(guān)于 API 版本管理

關(guān)于 API 權(quán)限與安全

關(guān)于團(tuán)隊(duì)間的 API 互通

注：這是一篇會(huì)隱式羅列很多知識(shí)點(diǎn)的文章，您可以按需深度搜索進(jìn)行更進(jìn)一步的學(xué)習(xí)。當(dāng)年渴望看到這樣的文章的原因是：學(xué)習(xí)一個(gè)知識(shí)點(diǎn)其實(shí)只需要時(shí)間，對(duì)學(xué)生而言，時(shí)間不是問題，問題在于不知道該往哪些方向?qū)W T_T 。本文希望通過串講，梳理一下個(gè)人當(dāng)前了解到的 API 知識(shí)體系，整理的同時(shí)也希望能對(duì)大家有一點(diǎn)點(diǎn)幫助。

1、初識(shí) API 接口

記得在我初學(xué) web 開發(fā)的時(shí)候，后端框架相關(guān)的教程基本都會(huì)教學(xué)生寫渲染模版（不分語言），也就是說后端返回的是整個(gè)網(wǎng)頁(yè)的數(shù)據(jù)，瀏覽器只負(fù)責(zé)渲染。

一般這類模版在后端都會(huì)對(duì)應(yīng)一個(gè)路由，比如前端想登入一個(gè)看用戶信息的頁(yè)面，在 url 中輸入的訪問地址大概長(zhǎng)這樣：

https://ajun24.com/user

那個(gè)時(shí)候，我以為這樣的路由地址就是 API 概念的全部了......

值得一提的是：絕大部分后端教程都會(huì)簡(jiǎn)單教一下前端，在前端的補(bǔ)充教程中有一個(gè)必學(xué)的知識(shí)點(diǎn)，叫：AJAX。

老師大概率會(huì)演示一下 AJAX 這個(gè)技術(shù)怎么使用，寫個(gè)小 Demo，告訴大家可以這樣在頁(yè)面上發(fā)送異步請(qǐng)求。

這個(gè)技術(shù)請(qǐng)求的后端接口一般不會(huì)跳轉(zhuǎn)或返回一個(gè) html 頁(yè)面，大概率會(huì)返回一份 json 數(shù)據(jù)。我一直對(duì)這樣的接口和返回頁(yè)面數(shù)據(jù)的接口有著迷之困惑。直到我實(shí)習(xí)后明白了什么叫前后端分離開發(fā)......

但是為了教學(xué)方便，完整項(xiàng)目大概率還是會(huì)用渲染模版的方式講解，畢竟只在一套系統(tǒng)里寫代碼演示會(huì)方便很多。

當(dāng)年就是這樣學(xué)完了第一個(gè)項(xiàng)目，雖然對(duì)如何做一個(gè)軟件系統(tǒng)有了整體的認(rèn)識(shí)，但是對(duì) API 設(shè)計(jì)的認(rèn)識(shí)是非常弱的。

其實(shí)我在學(xué) AJAX 這個(gè)知識(shí)點(diǎn)的時(shí)候就在想：有沒有可能全部數(shù)據(jù)都通過類似 AJAX 這種方式獲取？這樣感覺會(huì)更方便一些。

后來實(shí)習(xí)的時(shí)候，前端同學(xué)告訴我：開發(fā)前需要先定義 API 哦。

當(dāng)然，他還告訴我：刪除一個(gè)東西不能用 POST 請(qǐng)求哦（捂臉）

后來導(dǎo)師提醒我：你需要去了解一下如何設(shè)計(jì) REST 風(fēng)格的 API。

自從那次出丑后，我明白了一個(gè)事情，一定要敢于把自己的不足"暴露"給愿意指點(diǎn)你的人看。就好比我們讀大學(xué)的時(shí)候最好要努力去找一份實(shí)習(xí)，每一次被拒以及每一份 offer 都會(huì)告訴我們，這個(gè)社會(huì)需要什么樣的人才，什么樣的技能可以幫助我們謀得一份工作。

在正式的面試場(chǎng)合下，或許我們更應(yīng)該條理清晰地和面試官介紹什么是表現(xiàn)層狀態(tài)轉(zhuǎn)換，但是在這篇文章中，我想把 REST 風(fēng)格的 API 稱為更容易讓人看懂的 API。

大家會(huì)發(fā)現(xiàn)符合 REST 風(fēng)格的 API 能非常容易地讓別人知道調(diào)用這個(gè) API 能干什么，比如：

GET/users#查詢用戶信息
PATCH/users/{user_id}#根據(jù)id更新某個(gè)用戶的信息，只部分更新客戶端提交的數(shù)據(jù)

按約定寫 API 就好比在 IT 領(lǐng)域說行話，大家只要看見你的 API，就知道你能提供什么樣的服務(wù)。

有同學(xué)可能會(huì)好奇為什么要遵守規(guī)范？

假如，我們負(fù)責(zé)的系統(tǒng)僅聯(lián)系到我們身邊同事的系統(tǒng)，那約定 API 的時(shí)候只需要打個(gè)招呼，或在聊天工具上簡(jiǎn)單說明一下就可以了，甚至可以沒有文檔。

但在很多情況下，我們的系統(tǒng)是要被很多其他系統(tǒng)調(diào)用的，大家想象一下我們?nèi)フ{(diào)用云廠商 API 的場(chǎng)景：別人的工程師大概率不是我們的微信好友，大多數(shù)時(shí)候是沒有人站在我們身邊手把手告訴我們 API 怎么調(diào)用的。這個(gè)時(shí)候想調(diào)用對(duì)方提供的 API，就得看對(duì)方提供的 API 文檔。如果對(duì)方的 API 不按照規(guī)范定義，那 API 文檔絕對(duì)像天書一樣難讀。

看天書的痛苦，保證大家體會(huì)一次足以終生難忘。

良好的 API 文檔一般會(huì)像工具手冊(cè)，沒有太多學(xué)習(xí)成本，否則別人下一次很有可能就不使用我們的服務(wù)了

所以先系統(tǒng)地學(xué)習(xí) API 定義約規(guī)，再編寫 API 文檔，然后根據(jù)設(shè)計(jì)進(jìn)行開發(fā)是一個(gè)比較好的研發(fā)流程。

接下來的問題是，在了解了 API 的規(guī)范后，如何寫出良好的 API 文檔呢？

眾所周知，寫文檔對(duì)程序員來說是一件非常痛苦的事情，一想到學(xué)習(xí)寫專業(yè)的 API 文檔還需要學(xué)習(xí)成本，實(shí)在是勸退。這個(gè)時(shí)候我們可以通過一些自動(dòng)化工具輔助我們完成一篇優(yōu)秀的 API 文檔，比如我們可以使用 swagger，它可以通過我們的代碼自動(dòng)生成 API 文檔。

最近還看到不少基于 API 的研發(fā)測(cè)試一體化產(chǎn)品和平臺(tái)，感覺一站式的、流水線式的研發(fā)管理是未來的趨勢(shì)呀！

2. 關(guān)于 API 限流

API 寫出來后會(huì)被調(diào)用，但由于計(jì)算機(jī) & 網(wǎng)絡(luò)系統(tǒng)的局限性，我們的 API 接口是不可以被無限制調(diào)用的。

大家可以隨便到網(wǎng)上挑一個(gè)比較專業(yè)的 API 文檔看，比如大家可以去看云廠商對(duì)外提供的 API，基本都會(huì)看到一個(gè)接口頻率調(diào)用限制，比如：?jiǎn)斡脩粽{(diào)用頻率為 30 次 / 秒。

所以當(dāng)我們?cè)谠O(shè)計(jì) API 的時(shí)候，限流是一個(gè)不得不考慮的事情（內(nèi)部自己弄著玩的不算哈，泛指面向用戶的系統(tǒng)）

在設(shè)計(jì)限流之前，我們首先要知道自己系統(tǒng)的瓶頸。假設(shè)我們的 API 純粹調(diào)用自家的技術(shù)組件，比如數(shù)據(jù)庫(kù)，消息隊(duì)列等中間件，這個(gè)時(shí)候我們可以通過壓測(cè)得知一個(gè)接口的最大承受能力；假設(shè)我們的系統(tǒng)是一個(gè)中間系統(tǒng)，需要依賴其他系統(tǒng)的接口完成業(yè)務(wù)，那么這個(gè)時(shí)候基于木桶原理，我們接口的可訪問頻率就會(huì)受限于其他業(yè)務(wù)系統(tǒng)。

了解完自身項(xiàng)目的訪問瓶頸后，需要考慮自身系統(tǒng)的架構(gòu)，假設(shè)我們的系統(tǒng)是單體部署：

那這個(gè)時(shí)候我們只需要簡(jiǎn)單的令牌桶算法即可以完成限流，下面是一個(gè)極簡(jiǎn)的令牌桶算法實(shí)現(xiàn) Demo：

"""
簡(jiǎn)單解釋：
實(shí)現(xiàn)一個(gè)固定容量的桶，按一定的頻率往桶內(nèi)放令牌直至桶滿，每當(dāng)執(zhí)行一個(gè)限頻操作需要從桶中獲取一個(gè)令牌才能繼續(xù)操作，若桶中沒有令牌，則進(jìn)行等待
往令牌桶中放令牌的操作不便按照原概念實(shí)現(xiàn)，所以放令牌這步放到取令牌的時(shí)候進(jìn)行。我們根據(jù)當(dāng)前取令牌的時(shí)間減去上一次取令牌的時(shí)間差，就能得知這段時(shí)間內(nèi)增加了多少個(gè)令牌。
""
classTokenBucket(object):

#rate是令牌桶生產(chǎn)令牌的速率，capacity是令牌桶生產(chǎn)令牌的速率
def__init__(self,rate,capacity):
self._rate=rate
self._capacity=capacity
self._current_amount=0
self._last_consume_time=int(time.time())

#token_amount是執(zhí)行一次操作需要的令牌數(shù)量
defconsume(self,token_amount):
#通過時(shí)間差乘速率，得到令牌的增量
increment=(int(time.time())-self._last_consume_time)*self._rate
時(shí)間差乘速率，得到令牌的增量
self._current_amount=min(
increment+self._current_amount,self._capacity)
#令牌數(shù)量不夠則不允許操作
iftoken_amount>self._current_amount:
returnFalse
#更新最后一次操作時(shí)間
self._last_consume_time=int(time.time())
#結(jié)算當(dāng)前的令牌數(shù)量
self._current_amount-=token_amount
returnTrue
但實(shí)際工作中，我們部署單體架構(gòu)的機(jī)會(huì)不多，現(xiàn)在的大公司都構(gòu)建有自己的云生態(tài)，業(yè)務(wù)部門上云后可快速進(jìn)行擴(kuò)縮容，所以我們的系統(tǒng)很有可能會(huì)進(jìn)行集群部署，用戶的請(qǐng)求通過代理層負(fù)載均衡至各個(gè)后端節(jié)點(diǎn)：

這個(gè)時(shí)候上面的 15 行代碼顯然就不符合我們的分布式系統(tǒng)架構(gòu)，我們得考慮更復(fù)雜的限流算法實(shí)現(xiàn)了（這里不是指令牌桶算法不合適，是指令牌桶算法的實(shí)現(xiàn)方式需要改進(jìn)），當(dāng)然這個(gè)實(shí)現(xiàn)大概率會(huì)放在代理層了，而不是實(shí)現(xiàn)在我們的業(yè)務(wù)層。

大家可以上網(wǎng)看一下主流云廠商提供的云服務(wù)，很多都會(huì)提供 API 網(wǎng)關(guān)，對(duì)應(yīng)著我們上面提到的代理層。

假如一個(gè)公司有統(tǒng)一的 API 網(wǎng)關(guān)服務(wù)，或有類似的代理服務(wù)，業(yè)務(wù)部門是可以在 API 限流這件事情上省下很大功夫的。我有時(shí)候想，當(dāng)越來越多的中小企業(yè)基于巨無霸云廠商搭建業(yè)務(wù)，大家要考慮的技術(shù)性問題就會(huì)越來越少，越來越專注于業(yè)務(wù)，這到底是一件好事還是壞事呢？

3、關(guān)于 API 版本管理

介紹完 API 及限流的基本知識(shí)后，談一下和業(yè)務(wù)比較相關(guān)的 API 的版本管理。

在沒真正接觸業(yè)務(wù)前，我以為只有軟件需要做版本管理，為啥 API 也要做版本管理咧？

其實(shí)原理是一樣的，軟件會(huì)根據(jù)需求不斷迭代版本，API 同樣也會(huì)迭代版本，但秉承開閉原則，為了不影響之前的業(yè)務(wù)，我們最好不要改動(dòng)原有的 API。

因此，我們?cè)O(shè)計(jì) API 的時(shí)候可以指定版本號(hào)，比如上述的例子：

GET/users#查詢用戶信息

我們可以統(tǒng)一定義成：

GET/api/v1/users#查詢用戶信息

假設(shè)這個(gè)接口有了第二個(gè)版本，我們就可以通過版本號(hào)進(jìn)行區(qū)分了：

GET/api/v2/users#查詢用戶詳細(xì)信息

換作兩年前的我可能會(huì)對(duì) API 版本管理無感，但大家嘗試把自己代入以下場(chǎng)景就能明白了：

比如我們的產(chǎn)品讓我們出一套新的查詢用戶 API，假設(shè)我們沒有定義版本號(hào)，由于/users這條路由已經(jīng)在用了，逼不得已，我們就會(huì)定義一個(gè)新的：

GET/get_user_info#查詢用戶信息

新接口和老接口的意思差不多，如果我們一直負(fù)責(zé)這個(gè)系統(tǒng)，那還好說（心里有不同版本的區(qū)分）

但假如這個(gè)系統(tǒng)換了另一個(gè)接班人，當(dāng)他面對(duì)大量意義接近的接口時(shí)，肯定會(huì)懷疑人生的......（屎山就是這樣來的）

4. 關(guān)于 API 權(quán)限與安全

接著我們思考一下 API 的權(quán)限與安全問題。

還是回到初學(xué)的時(shí)候，那個(gè)時(shí)候我對(duì) API 接口權(quán)限完全沒有任何概念。老師為了快速教會(huì)我們開發(fā)系統(tǒng)，很多接口的設(shè)計(jì)是完全裸奔的。如果不了解一點(diǎn)點(diǎn)相關(guān)的知識(shí)，工作中會(huì)容易給別人一種考慮事情不周到的感覺。

在實(shí)際生產(chǎn)中，接口是不可以不做權(quán)限校驗(yàn)的，如果我們的系統(tǒng)暴露在公網(wǎng)，還沒有權(quán)限校驗(yàn)的話，系統(tǒng)估計(jì)很快就掛了；內(nèi)部涉及機(jī)密的系統(tǒng)，權(quán)限校驗(yàn)則更為嚴(yán)格。

關(guān)于權(quán)限校驗(yàn)，個(gè)人暫時(shí)分為三個(gè)維度，三個(gè)維度或許可以對(duì)應(yīng)三種業(yè)務(wù)類型：

第一種是直接針對(duì) IP 設(shè)置白名單，這種方式比較適用于客戶端有限且固定的內(nèi)部系統(tǒng)；

第二種則是設(shè)置權(quán)限校驗(yàn)流程，比如采用 Token 鑒權(quán)，較多用于 ToB 業(yè)務(wù)。大家在云廠商注冊(cè)賬號(hào)后基本都會(huì)得到一對(duì)密鑰，后續(xù)的 API 調(diào)用一般都需要先根據(jù)密鑰進(jìn)行權(quán)限認(rèn)證；

第三種是通過用戶登陸判斷權(quán)限，較多用于 ToC 業(yè)務(wù)，比如我們登陸京東，登陸淘寶需要賬號(hào)，沒有登陸就訪問不了購(gòu)物車等頁(yè)面。

值得一提的是，權(quán)限設(shè)計(jì)是另一個(gè)維度的知識(shí)，除了第一個(gè)維度，后兩者其實(shí)都可以單獨(dú)成立一個(gè)系統(tǒng)的。比如公司的用戶管理系統(tǒng)，中心化權(quán)限認(rèn)證系統(tǒng)等等。

權(quán)限校驗(yàn)關(guān)乎著公司財(cái)產(chǎn)安全，所以不可忽視，很多時(shí)候我們甚至需要在 API 設(shè)計(jì)層面考慮安全問題。再次引用商城的例子，比如登陸后獲取用戶購(gòu)物車的訂單，API 大概率會(huì)設(shè)計(jì)成這樣子：

GET/users/287435/orders

但直接暴露用戶 id 或許不是一個(gè)明智的選擇，有可能被不法分子利用，我們可以換種方式，比如用以下的方式替代：

GET/users/me/orders

總而言之，API 的設(shè)計(jì)除了參考規(guī)范外，還需要根據(jù)自身業(yè)務(wù)情況進(jìn)行更進(jìn)一步的安全考慮。

5、關(guān)于團(tuán)隊(duì)間的 API 互通

最后是一個(gè)延展性話題，相信大家都感受到了我們正身處于一個(gè)數(shù)據(jù)時(shí)代，我們的個(gè)人信息，包括各類行為喜好，都存放在各家互聯(lián)網(wǎng)公司的數(shù)據(jù)倉(cāng)庫(kù)里，企業(yè)們可能比我們更了解我們自身，網(wǎng)上也有很多與數(shù)據(jù)資產(chǎn)有關(guān)的話題。

既然已經(jīng)把數(shù)據(jù)比作資產(chǎn)了，而資產(chǎn)流動(dòng)性又是一個(gè)經(jīng)久不衰的話題，所以各類數(shù)據(jù)的開放性問題也倍受關(guān)注。而數(shù)據(jù)對(duì)外開放，必然就會(huì)涉及到 API 接口。

當(dāng)然作為一只小碼農(nóng)，我的視野極其有限，很難從一個(gè)較高的層次去談?wù)撈髽I(yè)的數(shù)據(jù)問題。但在工作中，當(dāng)其他業(yè)務(wù)團(tuán)隊(duì)提出要調(diào)用自己負(fù)責(zé)的項(xiàng)目的 API 接口時(shí)，也是需要進(jìn)行多方位考慮的。

本文列出的就是個(gè)人會(huì)從技術(shù)上考慮的點(diǎn)，總結(jié)成三句話就是：

你能看懂我的 API 嘛？

別把我的 API 打爆哦！

API 要經(jīng)允許才能使用哦！

由于API 的這個(gè)概念實(shí)在是太大了，我能接觸的也是一些些皮毛，但時(shí)不時(shí)總結(jié)整理一下還是大有裨益的。

編輯：黃飛