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

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

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

修改用戶的收貨地址

POST/xxx-mall/cart/update_address

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

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

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

初識 API 接口

關于 API 限流

關于 API 版本管理

關于 API 權限與安全

關于團隊間的 API 互通

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

1、初識 API 接口

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

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

https://ajun24.com/user

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

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

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

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

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

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

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

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

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

后來導師提醒我：你需要去了解一下如何設計 REST 風格的 API。

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

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

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

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

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

有同學可能會好奇為什么要遵守規(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 文檔一般會像工具手冊，沒有太多學習成本，否則別人下一次很有可能就不使用我們的服務了

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

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

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

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

2. 關于 API 限流

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

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

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

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

了解完自身項目的訪問瓶頸后，需要考慮自身系統(tǒng)的架構，假設我們的系統(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())
#結算當前的令牌數(shù)量
self._current_amount-=token_amount
returnTrue
但實際工作中，我們部署單體架構的機會不多，現(xiàn)在的大公司都構建有自己的云生態(tài)，業(yè)務部門上云后可快速進行擴縮容，所以我們的系統(tǒng)很有可能會進行集群部署，用戶的請求通過代理層負載均衡至各個后端節(jié)點：

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

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

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

3、關于 API 版本管理

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

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

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

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

GET/users#查詢用戶信息

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

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

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

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

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

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

GET/get_user_info#查詢用戶信息

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

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

4. 關于 API 權限與安全

接著我們思考一下 API 的權限與安全問題。

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

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

關于權限校驗，個人暫時分為三個維度，三個維度或許可以對應三種業(yè)務類型：

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

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

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

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

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

GET/users/287435/orders

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

GET/users/me/orders

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

5、關于團隊間的 API 互通

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

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

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

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

你能看懂我的 API 嘛？

別把我的 API 打爆哦！

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

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

編輯：黃飛