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

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

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

修改用戶的收貨地址

POST/xxx-mall/cart/update_address

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

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

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

初識 API 接口

關(guān)于 API 限流

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

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

關(guān)于團隊間的 API 互通

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

1、初識 API 接口

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

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

https://ajun24.com/user

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

值得一提的是：絕大部分后端教程都會簡單教一下前端，在前端的補充教程中有一個必學(xué)的知識點，叫：AJAX。

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

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

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

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

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

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

當然，他還告訴我：刪除一個東西不能用 POST 請求哦（捂臉）

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

"""
簡單解釋：
實現(xiàn)一個固定容量的桶，按一定的頻率往桶內(nèi)放令牌直至桶滿，每當執(zhí)行一個限頻操作需要從桶中獲取一個令牌才能繼續(xù)操作，若桶中沒有令牌，則進行等待
往令牌桶中放令牌的操作不便按照原概念實現(xiàn)，所以放令牌這步放到取令牌的時候進行。我們根據(jù)當前取令牌的時間減去上一次取令牌的時間差，就能得知這段時間內(nèi)增加了多少個令牌。
""
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):
#通過時間差乘速率，得到令牌的增量
increment=(int(time.time())-self._last_consume_time)*self._rate
時間差乘速率，得到令牌的增量
self._current_amount=min(
increment+self._current_amount,self._capacity)
#令牌數(shù)量不夠則不允許操作
iftoken_amount>self._current_amount:
returnFalse
#更新最后一次操作時間
self._last_consume_time=int(time.time())
#結(jié)算當前的令牌數(shù)量
self._current_amount-=token_amount
returnTrue
但實際工作中，我們部署單體架構(gòu)的機會不多，現(xiàn)在的大公司都構(gòu)建有自己的云生態(tài)，業(yè)務(wù)部門上云后可快速進行擴縮容，所以我們的系統(tǒng)很有可能會進行集群部署，用戶的請求通過代理層負載均衡至各個后端節(jié)點：

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

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

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

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

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

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

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

因此，我們設(shè)計 API 的時候可以指定版本號，比如上述的例子：

GET/users#查詢用戶信息

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

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

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

GET/api/v2/users#查詢用戶詳細信息

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

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

GET/get_user_info#查詢用戶信息

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

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

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

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

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

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

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

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

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

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

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

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

GET/users/287435/orders

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

GET/users/me/orders

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

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

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

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

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

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

你能看懂我的 API 嘛？

別把我的 API 打爆哦！

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

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

編輯：黃飛