一、前后端接口設計規范

建議采用RESTful 方式來實施。

• 說明1：采用RestFul方式實施接口通用性強，異構性強。
• 說明2：對于使用如Dubbo這樣的框架，限于java一種語言范圍內，在Provider與Consumer兩側共享一個client.jar包的情形，需要另外包裝成RESTFul接口以向外發布。但對于使用Spring Cloud這樣框架的新開應用，天然具有采用RestFul方式來實施的便利性。

協議
API與用戶的通信協議，總是使用HTTPs協議，確保交互數據的傳輸安全。

域名

• 應該盡量將API部署在專用域名之下。 https://api.example.com

• 如果確定API很簡單，不會有進一步擴展，可以考慮放在主域名下。 https://example.org/api/

api版本控制

• 應該將API的版本號放入URL。

https://api.example.com/v{n}/

• 另一種做法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。Github采用這種做法。

采用多版本并存，增量發布的方式
v{n} n代表版本號,分為整形和浮點型

• 整形的版本號:大功能版本發布形式；具有當前版本狀態下的所有API接口 ,例如：v1,v2
• 浮點型：為小版本號，只具備補充api的功能，其他api都默認調用對應大版本號的api 例如：v1.1 v2.2

已經開放出的接口，不允許修改方法簽名（外部接口的URL），避免對接口調用方產生影響。接口過時必須加@deprecated 注解，并清晰地說明采用的新接口或者新服務是什么。

API 路徑規則
路徑又稱"終點"（endpoint），表示API的具體網址。
在RESTful架構中，每個網址代表一種資源（resource），所以網址中不能有動詞，只能有名詞，而且所用的名詞往往與數據庫的表格名對應。一般來說，數據庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應該使用復數。
舉例來說，有一個API提供動物園（zoo）的信息，還包括各種動物和雇員的信息，則它的路徑應該設計成下面這樣。

• https://api.example.com/v1/products
• https://api.example.com/v1/users
• https://api.example.com/v1/employees

HTTP請求方式

對于資源的具體操作類型，由HTTP動詞表示。
常用的HTTP動詞有下面四個（括號里是對應的SQL命令）。

• GET（SELECT）：從服務器取出資源（一項或多項）。
• POST（CREATE）：在服務器新建一個資源。
• PUT（UPDATE）：在服務器更新資源（客戶端提供改變后的完整資源）。
• DELETE（DELETE）：從服務器刪除資源。

下面是一些例子。

• GET /product：列出所有商品
• POST /product：新建一個商品
• GET /product/ID：獲取某個指定商品的信息
• PUT /product/ID：更新某個指定商品的信息 DELETE /product/ID：刪除某個商品
• GET/product/ID/purchase ：列出某個指定商品的所有投資者
• GET /product/ID/purchase/ID：獲取某個指定商品的指定投資者信息

過濾信息
如果記錄數量很多，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。

下面是一些常見的參數。

• ?limit=10：指定返回記錄的數量 ?offset=10：指定返回記錄的開始位置。
• ?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
• ?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
• ?producy_type=1：指定篩選條件

API 傳入參數
參入參數分為4種類型：

地址欄參數

• restful 地址欄參數 /api/v1/product/122 122為產品編號，獲取產品為122的信息
• get方式的查詢字串 見過濾信息小節

請求body數據

cookie

request header

cookie和header 一般都是用于OAuth認證的2種途徑

返回數據
只要api接口成功接到請求，就不能返回200以外的HTTP狀態。
為了保障前后端的數據交互的順暢，建議規范數據的返回，并采用固定的數據格式封裝。

接口返回模板：

{status:0,data:{}||[],msg:’’ }

status: 接口的執行的狀態

> =0表示成功 <0 表示有異常 >0 表示接口有部分執行失敗

Data 接口的主數據

可以根據實際返回數組或JSON對象

Msg

當status!=0 都應該有錯誤信息

接口安全

開放接口供外部使用，需要關注接口運行的安全性，比如可以通過使用漏桶和令牌桶等算法來進行接口的限流、通過非對稱加密等方式來保護接口數據的安全性、通過使用時間戳加整個url簽名的方式來防止重放攻擊和進行限流保護。

對外提供的開放接口，需要進行參數有效性校驗。不合法入參的接口請求在校驗階段就應該返回了，不至于繼續操作后臺數據庫或其他數據存儲。

對外提供的開放接口，需要提供入參保護，包括檢查入參有效值的范圍、檢查入參落在白名單列表范圍、批量查詢操作的數據量范圍等。

api接口文檔

后端接口開發中，使用類似于Swagger
、Api2Doc等接口管理工具，定義接口內容包含：接口名稱（name），接口地址（url），輸入參數（params），返回值(data)，錯誤碼(errorCode)，錯誤信息(errorMessage)。

非Restful Api的需求

由于實際業務開展過程中，可能會出現各種的api不是簡單的restful 規范能實現的，因此，需要有一些api突破restful規范原則。特別是移動互聯網的api設計，更需要有一些特定的api來優化數據請求的交互。

跨域

前后端分離后，接口所在域名和前端展示邏輯代碼不在一個域名，但由于瀏覽器同源策略限制，前端AJAX請求無法獲取數據，因此需要來解決跨域問題。
常見的跨越方案有JSONP,CORS, nginx或node代理跨域；jsonp的安全性會降低，nginx或node代理會增加api服務,CORS相對最容易，也比較安全；服務端設置Access-Control-Allow-Origin：*；如果接口需要讀取cookie的話，那么前端也需要做一些簡單的配置。

• java示例：

// 允許跨域訪問的域名：若有端口需寫全（協議+域名+端口），若沒有端口末尾不用加'/' response.setHeader("Access-Control-Allow-Origin", "http://www.domain1.com"); // 允許前端帶認證cookie：啟用此項后，上面的域名不能為'*'，必須指定具體的域名 response.setHeader("Access-Control-Allow-Credentials", "true");

總結

以上是生活随笔為你收集整理的前后端接口设计规范的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。