程序員不得不知道的 API 接口常識
實話，我非常希望自己能早點看到本篇文章，大學那個時候懵懵懂懂，跟著網上的免費教程做了一個購物商城就屁顛屁顛往簡歷上寫。
至今我仍清晰地記得，那個電商教程是怎么定義接口的：
管它是增加、修改、刪除、帶參查詢，全是 POST 請求一把梭，比如下面這樣：
修改用戶的收貨地址
POST /xxx-mall/cart/update_address
現在看來，全部用 POST 請求估計是為了傳參方便吧。
那個時候自己也沒有一個 API 接口需要設計 的意識，跟學過類似教程的朋友應該懂的，老師敲一行代碼學生跟著敲一行。如果沒人提這個事情，正式工作進入團隊后，是很容易出丑的......（作者親身經歷，捂臉）
本文就不用 PPT 教案上的那種官方腔介紹 API 接口是個什么概念了，比較希望用一種聊天的方式和大家分享下現有的一丁丁和 API 相關的小心得，文章會分為五小塊：
- 初識 API 接口
- 關于 API 限流
- 關于 API 版本管理
- 關于 API 權限與安全
- 關于團隊間的 API 互通
- 注：這是一篇會隱式羅列很多知識點的文章，您可以按需深度搜索進行更進一步的學習。當年渴望看到這樣的文章的原因是：學習一個知識點其實只需要時間，對學生而言，時間不是問題，問題在于不知道該往哪些方向學 T_T 。本文希望通過串講，梳理一下個人當前了解到的 API 知識體系，整理的同時也希望能對大家有一點點幫助。
1、初識 API 接口
記得在我初學 web 開發的時候，后端框架相關的教程基本都會教學生寫渲染模版（不分語言），也就是說后端返回的是整個網頁的數據，瀏覽器只負責渲染。
一般這類模版在后端都會對應一個路由，比如前端想登入一個看用戶信息的頁面，在 url 中輸入的訪問地址大概長這樣：
https://ajun24.com/user
那個時候，我以為這樣的路由地址就是 API 概念的全部了......
值得一提的是：絕大部分后端教程都會簡單教一下前端，在前端的補充教程中有一個必學的知識點，叫：AJAX。
老師大概率會演示一下 AJAX 這個技術怎么使用，寫個小 Demo，告訴大家可以這樣在頁面上發送異步請求。
這個技術請求的后端接口一般不會跳轉或返回一個 html 頁面，大概率會返回一份 json 數據。我一直對這樣的接口和返回頁面數據的接口有著迷之困惑。直到我實習后明白了什么叫前后端分離開發......
但是為了教學方便，完整項目大概率還是會用渲染模版的方式講解，畢竟只在一套系統里寫代碼演示會方便很多。
當年就是這樣學完了第一個項目，雖然對如何做一個軟件系統有了整體的認識，但是對 API 設計的認識是非常弱的。
其實我在學 AJAX 這個知識點的時候就在想：有沒有可能全部數據都通過類似 AJAX 這種方式獲取？這樣感覺會更方便一些。
后來實習的時候，前端同學告訴我：開發前需要先定義 API 哦。
當然，他還告訴我：刪除一個東西不能用 POST 請求哦圖片（捂臉）
后來導師提醒我：你需要去了解一下如何設計 REST 風格的 API。
- 自從那次出丑后，我明白了一個事情，一定要敢于把自己的不足暴露給愿意指點你的人看。就好比我們讀大學的時候最好要努力去找一份實習，每一次被拒以及每一份 offer 都會告訴我們，這個社會需要什么樣的人才，什么樣的技能可以幫助我們謀得一份工作。
在正式的面試場合下，或許我們更應該條理清晰地和面試官介紹什么是表現層狀態轉換，但是在這篇文章中，我想把 REST 風格的 API 稱為更容易讓人看懂的 API。
大家會發現符合 REST 風格的 API 能非常容易地讓別人知道調用這個 API 能干什么，比如：
GET /users # 查詢用戶信息
PATCH /users/{user_id} # 根據 id 更新某個用戶的信息，只部分更新客戶端提交的數據
按約定寫 API 就好比在 IT 領域說行話，大家只要看見你的 API，就知道你能提供什么樣的服務。
有同學可能會好奇為什么要遵守規范？
假如，我們負責的系統僅聯系到我們身邊同事的系統，那約定 API 的時候只需要打個招呼，或在聊天工具上簡單說明一下就可以了，甚至可以沒有文檔。
但在很多情況下，我們的系統是要被很多其他系統調用的，大家想象一下我們去調用云廠商 API 的場景：別人的工程師大概率不是我們的微信好友，大多數時候是沒有人站在我們身邊手把手告訴我們 API 怎么調用的。這個時候想調用對方提供的 API，就得看對方提供的 API 文檔。如果對方的 API 不按照規范定義，那 API 文檔絕對像天書一樣難讀。
看天書的痛苦，保證大家體會一次足以終生難忘。
良好的 API 文檔一般會像工具手冊，沒有太多學習成本，否則別人下一次很有可能就不使用我們的服務了圖片
所以先系統地學習 API 定義約規，再編寫 API 文檔，然后根據設計進行開發是一個比較好的研發流程。
接下來的問題是，在了解了 API 的規范后，如何寫出良好的 API 文檔呢？
眾所周知，寫文檔對程序員來說是一件非常痛苦的事情，一想到學習寫專業的 API 文檔還需要學習成本，實在是勸退。這個時候我們可以通過一些自動化工具輔助我們完成一篇優秀的 API 文檔，比如我們可以使用 swagger，它可以通過我們的代碼自動生成 API 文檔。
最近還看到不少基于 API 的研發測試一體化產品和平臺，感覺一站式的、流水線式的研發管理是未來的趨勢呀！
2. 關于 API 限流
API 寫出來后會被調用，但由于計算機 & 網絡系統的局限性，我們的 API 接口是不可以被無限制調用的。
大家可以隨便到網上挑一個比較專業的 API 文檔看，比如大家可以去看云廠商對外提供的 API，基本都會看到一個接口頻率調用限制，比如：單用戶調用頻率為 30 次 / 秒。
所以當我們在設計 API 的時候，限流是一個不得不考慮的事情（內部自己弄著玩的不算哈，泛指面向用戶的系統）
在設計限流之前，我們首先要知道自己系統的瓶頸。假設我們的 API 純粹調用自家的技術組件，比如數據庫，消息隊列等中間件，這個時候我們可以通過壓測得知一個接口的最大承受能力；假設我們的系統是一個中間系統，需要依賴其他系統的接口完成業務，那么這個時候基于木桶原理，我們接口的可訪問頻率就會受限于其他業務系統。
了解完自身項目的訪問瓶頸后，需要考慮自身系統的架構，假設我們的系統是單體部署：
那這個時候我們只需要簡單的令牌桶算法即可以完成限流，下面是一個極簡的令牌桶算法實現 Demo：
簡單解釋：
實現一個固定容量的桶，按一定的頻率往桶內放令牌直至桶滿，每當執行一個限頻操作需要從桶中獲取一個令牌才能繼續操作，若桶中沒有令牌，則進行等待
往令牌桶中放令牌的操作不便按照原概念實現，所以放令牌這步放到取令牌的時候進行。我們根據當前取令牌的時間減去上一次取令牌的時間差，就能得知這段時間內增加了多少個令牌。
class TokenBucket(object):
# rate 是令牌桶生產令牌的速率，capacity 是令牌桶生產令牌的速率
def __init__(self, rate, capacity):
self._rate = rate
self._capacity = capacity
self._current_amount = 0
self._last_consume_time = int(time.time())
# token_amount 是執行一次操作需要的令牌數量
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)
# 令牌數量不夠則不允許操作
if token_amount > self._current_amount:
return False
# 更新最后一次操作時間
self._last_consume_time = int(time.time())
# 結算當前的令牌數量
self._current_amount -= token_amount
return True
但實際工作中，我們部署單體架構的機會不多，現在的大公司都構建有自己的云生態，業務部門上云后可快速進行擴縮容，所以我們的系統很有可能會進行集群部署，用戶的請求通過代理層負載均衡至各個后端節點：
這個時候上面的 15 行代碼顯然就不符合我們的分布式系統架構，我們得考慮更復雜的限流算法實現了（這里不是指令牌桶算法不合適，是指令牌桶算法的實現方式需要改進），當然這個實現大概率會放在代理層了，而不是實現在我們的業務層。
大家可以上網看一下主流云廠商提供的云服務，很多都會提供 API 網關，對應著我們上面提到的代理層。
假如一個公司有統一的 API 網關服務，或有類似的代理服務，業務部門是可以在 API 限流這件事情上省下很大功夫的。我有時候想，當越來越多的中小企業基于巨無霸云廠商搭建業務，大家要考慮的技術性問題就會越來越少，越來越專注于業務，這到底是一件好事還是壞事呢？
3、關于 API 版本管理
介紹完 API 及限流的基本知識后，談一下和業務比較相關的 API 的版本管理。
在沒真正接觸業務前，我以為只有軟件需要做版本管理，為啥 API 也要做版本管理咧？
其實原理是一樣的，軟件會根據需求不斷迭代版本，API 同樣也會迭代版本，但秉承開閉原則，為了不影響之前的業務，我們最好不要改動原有的 API。
因此，我們設計 API 的時候可以指定版本號，比如上述的例子：
GET /users # 查詢用戶信息
我們可以統一定義成：
GET /api/v1/users # 查詢用戶信息
假設這個接口有了第二個版本，我們就可以通過版本號進行區分了：
GET /api/v2/users # 查詢用戶詳細信息
換作兩年前的我可能會對 API 版本管理無感，但大家嘗試把自己代入以下場景就能明白了：
比如我們的產品讓我們出一套新的查詢用戶 API，假設我們沒有定義版本號，由于 /users 這條路由已經在用了，逼不得已，我們就會定義一個新的：
GET /get_user_info # 查詢用戶信息
新接口和老接口的意思差不多，如果我們一直負責這個系統，那還好說（心里有不同版本的區分）
但假如這個系統換了另一個接班人，當他面對大量意義接近的接口時，肯定會懷疑人生的......（屎山就是這樣來的）
4. 關于 API 權限與安全
接著我們思考一下 API 的權限與安全問題。
還是回到初學的時候，那個時候我對 API 接口權限完全沒有任何概念。老師為了快速教會我們開發系統，很多接口的設計是完全裸奔的。如果不了解一點點相關的知識，工作中會容易給別人一種考慮事情不周到的感覺。
在實際生產中，接口是不可以不做權限校驗的，如果我們的系統暴露在公網，還沒有權限校驗的話，系統估計很快就掛了；內部涉及機密的系統，權限校驗則更為嚴格。
關于權限校驗，個人暫時分為三個維度，三個維度或許可以對應三種業務類型：
- 第一種是直接針對 IP 設置白名單，這種方式比較適用于客戶端有限且固定的內部系統；
- 第二種則是設置權限校驗流程，比如采用 Token 鑒權，較多用于 ToB 業務。大家在云廠商注冊賬號后基本都會得到一對密鑰，后續的 API 調用一般都需要先根據密鑰進行權限認證；
- 第三種是通過用戶登陸判斷權限，較多用于 ToC 業務，比如我們登陸京東，登陸淘寶需要賬號，沒有登陸就訪問不了購物車等頁面。
值得一提的是，權限設計是另一個維度的知識，除了第一個維度，后兩者其實都可以單獨成立一個系統的。比如公司的用戶管理系統，中心化權限認證系統等等。
權限校驗關乎著公司財產安全，所以不可忽視，很多時候我們甚至需要在 API 設計層面考慮安全問題。再次引用商城的例子，比如登陸后獲取用戶購物車的訂單，API 大概率會設計成這樣子：
GET /users/287435/orders
但直接暴露用戶 id 或許不是一個明智的選擇，有可能被不法分子利用，我們可以換種方式，比如用以下的方式替代：
GET /users/me/orders
總而言之，API 的設計除了參考規范外，還需要根據自身業務情況進行更進一步的安全考慮。
5、關于團隊間的 API 互通
最后是一個延展性話題，相信大家都感受到了我們正身處于一個數據時代，我們的個人信息，包括各類行為喜好，都存放在各家互聯網公司的數據倉庫里，企業們可能比我們更了解我們自身，網上也有很多與數據資產有關的話題。
既然已經把數據比作資產了，而資產流動性又是一個經久不衰的話題，所以各類數據的開放性問題也倍受關注。而數據對外開放，必然就會涉及到 API 接口。
當然作為一只小碼農，我的視野極其有限，很難從一個較高的層次去談論企業的數據問題。但在工作中，當其他業務團隊提出要調用自己負責的項目的 API 接口時，也是需要進行多方位考慮的。
本文列出的就是個人會從技術上考慮的點，總結成三句話就是：
- 你能看懂我的 API 嘛？
- 別把我的 API 打爆哦！
- API 要經允許才能使用哦！
由于API 的這個概念實在是太大了，我能接觸的也是一些些皮毛，但時不時總結整理一下還是大有裨益的。
