程序員不得不知道的 API 接口常識
實話，我非常希望自己能早點看到本篇文章，大學(xué)那個時候懵懵懂懂，跟著網(wǎng)上的免費教程做了一個購物商城就屁顛屁顛往簡歷上寫。
至今我仍清晰地記得，那個電商教程是怎么定義接口的：
管它是增加、修改、刪除、帶參查詢，全是 POST 請求一把梭，比如下面這樣：
修改用戶的收貨地址
POST /xxx-mall/cart/update_address
現(xiàn)在看來，全部用 POST 請求估計是為了傳參方便吧。
那個時候自己也沒有一個 API 接口需要設(shè)計 的意識，跟學(xué)過類似教程的朋友應(yīng)該懂的，老師敲一行代碼學(xué)生跟著敲一行。如果沒人提這個事情，正式工作進(jìn)入團(tuán)隊后，是很容易出丑的......（作者親身經(jīng)歷，捂臉）
本文就不用 PPT 教案上的那種官方腔介紹 API 接口是個什么概念了，比較希望用一種聊天的方式和大家分享下現(xiàn)有的一丁丁和 API 相關(guān)的小心得，文章會分為五小塊：
- 初識 API 接口
- 關(guān)于 API 限流
- 關(guān)于 API 版本管理
- 關(guān)于 API 權(quán)限與安全
- 關(guān)于團(tuán)隊間的 API 互通
- 注：這是一篇會隱式羅列很多知識點的文章，您可以按需深度搜索進(jìn)行更進(jìn)一步的學(xué)習(xí)。當(dāng)年渴望看到這樣的文章的原因是：學(xué)習(xí)一個知識點其實只需要時間，對學(xué)生而言，時間不是問題，問題在于不知道該往哪些方向?qū)W T_T 。本文希望通過串講，梳理一下個人當(dāng)前了解到的 API 知識體系，整理的同時也希望能對大家有一點點幫助。
1、初識 API 接口
記得在我初學(xué) web 開發(fā)的時候，后端框架相關(guān)的教程基本都會教學(xué)生寫渲染模版（不分語言），也就是說后端返回的是整個網(wǎng)頁的數(shù)據(jù)，瀏覽器只負(fù)責(zé)渲染。
一般這類模版在后端都會對應(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)里寫代碼演示會方便很多。
當(dāng)年就是這樣學(xué)完了第一個項目，雖然對如何做一個軟件系統(tǒng)有了整體的認(rèn)識，但是對 API 設(shè)計的認(rèn)識是非常弱的。
其實我在學(xué) AJAX 這個知識點的時候就在想：有沒有可能全部數(shù)據(jù)都通過類似 AJAX 這種方式獲?。窟@樣感覺會更方便一些。
后來實習(xí)的時候，前端同學(xué)告訴我：開發(fā)前需要先定義 API 哦。
當(dāng)然，他還告訴我：刪除一個東西不能用 POST 請求哦圖片（捂臉）
后來導(dǎo)師提醒我：你需要去了解一下如何設(shè)計 REST 風(fēng)格的 API。
- 自從那次出丑后，我明白了一個事情，一定要敢于把自己的不足暴露給愿意指點你的人看。就好比我們讀大學(xué)的時候最好要努力去找一份實習(xí)，每一次被拒以及每一份 offer 都會告訴我們，這個社會需要什么樣的人才，什么樣的技能可以幫助我們謀得一份工作。
在正式的面試場合下，或許我們更應(yīng)該條理清晰地和面試官介紹什么是表現(xiàn)層狀態(tài)轉(zhuǎn)換，但是在這篇文章中，我想把 REST 風(fēng)格的 API 稱為更容易讓人看懂的 API。
大家會發(fā)現(xiàn)符合 REST 風(fēng)格的 API 能非常容易地讓別人知道調(diào)用這個 API 能干什么，比如：
GET /users # 查詢用戶信息
PATCH /users/{user_id} # 根據(jù) id 更新某個用戶的信息，只部分更新客戶端提交的數(shù)據(jù)
按約定寫 API 就好比在 IT 領(lǐng)域說行話，大家只要看見你的 API，就知道你能提供什么樣的服務(wù)。
有同學(xué)可能會好奇為什么要遵守規(guī)范？
假如，我們負(fù)責(zé)的系統(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è)計進(jìn)行開發(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 次 / 秒。
所以當(dāng)我們在設(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)放令牌直至桶滿，每當(dāng)執(zhí)行一個限頻操作需要從桶中獲取一個令牌才能繼續(xù)操作，若桶中沒有令牌，則進(jìn)行等待
往令牌桶中放令牌的操作不便按照原概念實現(xiàn)，所以放令牌這步放到取令牌的時候進(jìn)行。我們根據(jù)當(dāng)前取令牌的時間減去上一次取令牌的時間差，就能得知這段時間內(nèi)增加了多少個令牌。
class TokenBucket(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ù)量
def consume(self, token_amount):
# 通過時間差乘速率，得到令牌的增量
increment = (int(time.time()) - self._last_consume_time) * self._rate
時間差乘速率，得到令牌的增量
self._current_amount = min(
increment + self._current_amount, self._capacity)
# 令牌數(shù)量不夠則不允許操作
if token_amount > self._current_amount:
return False
# 更新最后一次操作時間
self._last_consume_time = int(time.time())
# 結(jié)算當(dāng)前的令牌數(shù)量
self._current_amount -= token_amount
return True
但實際工作中，我們部署單體架構(gòu)的機會不多，現(xiàn)在的大公司都構(gòu)建有自己的云生態(tài)，業(yè)務(wù)部門上云后可快速進(jìn)行擴縮容，所以我們的系統(tǒng)很有可能會進(jìn)行集群部署，用戶的請求通過代理層負(fù)載均衡至各個后端節(jié)點：
這個時候上面的 15 行代碼顯然就不符合我們的分布式系統(tǒng)架構(gòu)，我們得考慮更復(fù)雜的限流算法實現(xiàn)了（這里不是指令牌桶算法不合適，是指令牌桶算法的實現(xiàn)方式需要改進(jìn)），當(dāng)然這個實現(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 限流這件事情上省下很大功夫的。我有時候想，當(dāng)越來越多的中小企業(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è)這個接口有了第二個版本，我們就可以通過版本號進(jìn)行區(qū)分了：
GET /api/v2/users # 查詢用戶詳細(xì)信息
換作兩年前的我可能會對 API 版本管理無感，但大家嘗試把自己代入以下場景就能明白了：
比如我們的產(chǎn)品讓我們出一套新的查詢用戶 API，假設(shè)我們沒有定義版本號，由于 /users 這條路由已經(jīng)在用了，逼不得已，我們就會定義一個新的：
GET /get_user_info # 查詢用戶信息
新接口和老接口的意思差不多，如果我們一直負(fù)責(zé)這個系統(tǒng)，那還好說（心里有不同版本的區(qū)分）
但假如這個系統(tǒng)換了另一個接班人，當(dā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)限校驗則更為嚴(yá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ù)密鑰進(jìn)行權(quán)限認(rèn)證；
- 第三種是通過用戶登陸判斷權(quán)限，較多用于 ToC 業(yè)務(wù)，比如我們登陸京東，登陸淘寶需要賬號，沒有登陸就訪問不了購物車等頁面。
值得一提的是，權(quán)限設(shè)計是另一個維度的知識，除了第一個維度，后兩者其實都可以單獨成立一個系統(tǒng)的。比如公司的用戶管理系統(tǒng)，中心化權(quán)限認(rè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ù)情況進(jìn)行更進(jìn)一步的安全考慮。
5、關(guān)于團(tuá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 接口。
當(dāng)然作為一只小碼農(nóng)，我的視野極其有限，很難從一個較高的層次去談?wù)撈髽I(yè)的數(shù)據(jù)問題。但在工作中，當(dāng)其他業(yè)務(wù)團(tuán)隊提出要調(diào)用自己負(fù)責(zé)的項目的 API 接口時，也是需要進(jìn)行多方位考慮的。
本文列出的就是個人會從技術(shù)上考慮的點，總結(jié)成三句話就是：
- 你能看懂我的 API 嘛？
- 別把我的 API 打爆哦！
- API 要經(jīng)允許才能使用哦！
由于API 的這個概念實在是太大了，我能接觸的也是一些些皮毛，但時不時總結(jié)整理一下還是大有裨益的。
