API介面設計最佳實踐

目錄前言

api介面設計

token設計

api介面設計原則

1、明確協議規範

2、統一介面路徑規範

3、統一介面版本管理

4、為你的介面設定呼叫門檻

5、介面返回規範

6、介面安全規範

7、冪等性

8、介面設計的一些最佳實踐

api介面管理

最近團隊內部在做故障覆盤的時候發現有很多故障都是因為介面設計不當導致的，這裡我就整理歸納一下在介面設計層面需要注意的地方。

token是服務端生成的一串字串，以作客戶端進行請求的乙個令牌，當第一次登入後，伺服器生成乙個token便將此token返回給客戶端，以後客戶端只需帶上這個token前來請求資料即可，無需再次帶上使用者名稱和密碼。

token的值一般用uuid（演算法比較著名的有雪花演算法），當服務端接收到客戶端請求後會生成token（一串字元，如etye0fgkgk4ca2ttdsl0ae9a5dd77471fgf），然後將token作為key將一些和token關聯的資訊作為value儲存到如redis快取資料庫中，同步把該token返回給客戶端；後續該客戶端的請求都需要帶上這個token，伺服器收到請求後就會去快取伺服器中匹配這個token是否存在，存在則呼叫介面，不存在返回介面錯誤。

token種類

在設計初期需要明確雙方的通訊協議是tcp、http、rpc，一般針對比較敏感的交易或者行業（如金融業），建議使用https協議以確保資料互動的安全。

post /recommend/cardlist

一般來說，介面的版本管理一般有以下兩種方法：

在url中加入version資訊，如下述；

在http header加入version資訊，這樣就等於只有乙個介面，但是具體的不同版本的業務邏輯由後台區分處理。

post v1/recommend/cardlist

nginx的路由分發： server location /v2/ }server server

為呼叫你的系統分配乙個id和key，針對每個請求對id和key進行校驗，避免在企業內網中的其他系統只要知道介面被可以隨意呼叫。

返回資料盡量統一規範，務必包括：返回碼、返回資訊、資料。

當我們開發的介面需要暴露到公網，這樣的風險跟我們在企業內網暴露給其他系統呼叫的風險是不可同日而語的。其中有很多風險需要我們一一解決。以下僅提供能想到的：

6.1.資料如何防止被看到？

目前業界老生常談就是對稱加密和非對稱加密。

對稱加密：對稱金鑰在加密和解密的過程中使用的金鑰是相同的，常見的對稱加密演算法有des，aes；優點是計算速度快，缺點是在資料傳送前，傳送方和接收方必須商定好秘鑰，然後使雙方都能儲存好秘鑰，如果一方的秘鑰被洩露，那麼加密資訊也就不安全了；

非對稱加密：服務端會生成一對金鑰，私鑰存放在伺服器端，公鑰可以發布給任何人使用；優點就是比起對稱加密更加安全，但是加解密的速度比對稱加密慢太多了；廣泛使用的是rsa演算法；

目前主流的做法是在傳輸層使用https協議，http和tcp之間新增一層加密層(ssl層)，這一層負責資料的加密和解密。https協議則是巧妙的利用上述兩種對稱加密方法；淺顯一點說就是客戶端和服務端建立三次握手連線過程中通過交換雙方非對稱公鑰，接著使用對方非對稱公鑰加密雙方約定好的對稱金鑰，這樣就只有雙方有這個對稱金鑰（這樣的非對稱加密可以保證很安全的把對稱金鑰給到對方）。後續雙方的報文溝通就可以使用該對稱金鑰進行加解密（這樣的對稱加密可以保證請求報文可以快速被解密處理，並在處理後被快速加密響應回去）。

6.2.資料如何防止給篡改？

這個時候我們需要對資料進行加簽，資料簽名平時用得比較多的是md5，即將需要提交的資料通過某種方式組合和乙個字串，然後通過md5生成一段加密字串，這段加密字串就是資料報的簽名。具體請看以下的圖。

6.3.時間戳機制

如果加密資料被抓包後被用於重放攻擊，我們怎麼辦？這個時候我們可以把解密後的url引數中的時間戳與系統時間進行比較，如果時間差超過一定間距（如5分鐘）即認為該報文被劫持並返回錯誤。但是，務必保證該時間戳的超時時間一定要跟sign儲存的有效時間一致。

客戶端在第一次訪問服務端時，服務端將sign快取到redis中並把有效時間設定為跟時間戳的超時時間一致；如果有人使用同乙個url再次訪問，如果發現快取伺服器中已經存在了本次的sign，則拒絕服務；如果在redis中的sign失效的情況下，有人使用同乙個url再次訪問，則會被時間戳超時機制攔截。這樣的話，就可以避免url被別人截獲後的重放攻擊。

整個流程如下：

1、客戶端通過使用者名稱密碼登入伺服器並獲取token

2、客戶端生成時間戳timestamp，並將timestamp作為其中乙個引數

3、客戶端將所有的引數，包括token和timestamp按照自己的演算法進行排序加密得到簽名sign

4、將token、timestamp和sign作為請求時必須攜帶的引數加在每個請求的url後邊（

5、服務端寫乙個過濾器對token、timestamp和sign進行驗證，只有在token有效、timestamp未超時、快取伺服器中不存在sign三種情況同時滿足，本次請求才有效。

6.4.隨機數機制另外，一般會在url引數上加上隨機數（即所謂的加鹽）並與6.3的時間戳機制組合使用以便提公升防重複提交攻擊。

6.5.黑名單機制

針對同乙個ip在短時間內頻繁請求的，可以通過nginx進行過濾，同步可以在nginx部署動態黑名單（即ip實時更新到黑名單庫），這樣可以防控少量的ddos。但受限於判斷黑名單需要考慮多維度的資訊，一般我們的nginx盡量只做同一ip校驗，更多維度的黑名單校驗可以通過廠商去解決。

6.6.資料合法性校驗

這裡的資料合法性校驗主要指的是資料格式校驗和業務規則校驗。

資料格式校驗：日期格式校驗、長度校驗、非空校驗等；

業務規則校驗：如庫存校驗、身份證合法性校驗等。

定義：在計算機中，表示對同乙個過程應用相同的引數多次和應用一次產生的效果是一樣，這樣的過程即被稱為滿足冪等性。

具體的解決方案有token機制、分布式鎖、狀態機等方案；這裡引用一下之前看到的一篇文章，寫得比較詳細：

一家公司的每個系統都會有各種各樣的介面，但是大部分公司，特別是傳統行業的公司的所謂介面文件更多是當每個系傳統的word文字格式，這種傳統的格式有著人盡皆知的痛點：1）維護不及時；2）與**不同步；3）歸檔後「便束之高閣」；4）介面文件跟**沒有互動；5）文字檢索無法建立全域性搜尋，需要額外借助工具。為了解決上述的問題，需要建立一套行之有效的介面管理體系，該體系的目標是：

能夠進行介面文件管理，作為後續的介面治理的其中一部分；

能作為介面測試的平台，這樣能保證介面跟**是同步的；

支援文字檢索。

業界有很多不同的api介面管理平台。如去哪兒網的yapi平台、阿里某團隊開發的rap平台、swagger、postman、easyapi。針對這一些平台的優劣對比，因為目前暫時還沒有真正用起來不好去評價，各位有興趣的自行搜尋學習。

API介面設計最佳實踐

服務端 API 介面設計最佳實踐

api介面設計

API介面設計

相關推薦