一、前后端接口設(shè)計(jì)規(guī)范

建議采用RESTful 方式來實(shí)施。

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

協(xié)議
API與用戶的通信協(xié)議，總是使用HTTPs協(xié)議，確保交互數(shù)據(jù)的傳輸安全。

域名

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

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

api版本控制

• 應(yīng)該將API的版本號放入URL。

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

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

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

• 整形的版本號:大功能版本發(fā)布形式；具有當(dāng)前版本狀態(tài)下的所有API接口 ,例如：v1,v2
• 浮點(diǎn)型：為小版本號，只具備補(bǔ)充api的功能，其他api都默認(rèn)調(diào)用對應(yīng)大版本號的api 例如：v1.1 v2.2

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

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

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

HTTP請求方式

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

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

下面是一些例子。

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

過濾信息
如果記錄數(shù)量很多，服務(wù)器不可能都將它們返回給用戶。API應(yīng)該提供參數(shù)，過濾返回結(jié)果。

下面是一些常見的參數(shù)。

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

API 傳入?yún)?shù)
參入?yún)?shù)分為4種類型：

地址欄參數(shù)

• restful 地址欄參數(shù) /api/v1/product/122 122為產(chǎn)品編號，獲取產(chǎn)品為122的信息
• get方式的查詢字串 見過濾信息小節(jié)

請求body數(shù)據(jù)

cookie

request header

cookie和header 一般都是用于OAuth認(rèn)證的2種途徑

返回?cái)?shù)據(jù)
只要api接口成功接到請求，就不能返回200以外的HTTP狀態(tài)。
為了保障前后端的數(shù)據(jù)交互的順暢，建議規(guī)范數(shù)據(jù)的返回，并采用固定的數(shù)據(jù)格式封裝。

接口返回模板：

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

status: 接口的執(zhí)行的狀態(tài)

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

Data 接口的主數(shù)據(jù)

可以根據(jù)實(shí)際返回?cái)?shù)組或JSON對象

Msg

當(dāng)status!=0 都應(yīng)該有錯誤信息

接口安全

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

對外提供的開放接口，需要進(jìn)行參數(shù)有效性校驗(yàn)。不合法入?yún)⒌慕涌谡埱笤谛ｒ?yàn)階段就應(yīng)該返回了，不至于繼續(xù)操作后臺數(shù)據(jù)庫或其他數(shù)據(jù)存儲。

對外提供的開放接口，需要提供入?yún)⒈Ｗo(hù)，包括檢查入?yún)⒂行е档姆秶z查入?yún)⒙湓诎酌麊瘟斜矸秶⑴坎樵儾僮鞯臄?shù)據(jù)量范圍等。

api接口文檔

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

非Restful Api的需求

由于實(shí)際業(yè)務(wù)開展過程中，可能會出現(xiàn)各種的api不是簡單的restful 規(guī)范能實(shí)現(xiàn)的，因此，需要有一些api突破restful規(guī)范原則。特別是移動互聯(lián)網(wǎng)的api設(shè)計(jì)，更需要有一些特定的api來優(yōu)化數(shù)據(jù)請求的交互。

跨域

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

• java示例：

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

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。