前后端接口设计规范
一、前后端接口設計規范
- 說明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的版本號放入URL。
- 另一種做法是,將版本號放在HTTP頭信息中,但不如放入URL方便和直觀。Github采用這種做法。
采用多版本并存,增量發布的方式
v{n} n代表版本號,分為整形和浮點型
- 整形的版本號:大功能版本發布形式;具有當前版本狀態下的所有API接口 ,例如:v1,v2
- 浮點型:為小版本號,只具備補充api的功能,其他api都默認調用對應大版本號的api 例如:v1.1 v2.2
已經開放出的接口,不允許修改方法簽名(外部接口的URL),避免對接口調用方產生影響。接口過時必須加@deprecated 注解,并清晰地說明采用的新接口或者新服務是什么。
路徑又稱"終點"(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動詞有下面四個(括號里是對應的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:指定篩選條件
參入參數分為4種類型:
- restful 地址欄參數 /api/v1/product/122 122為產品編號,獲取產品為122的信息
- get方式的查詢字串 見過濾信息小節
cookie和header 一般都是用于OAuth認證的2種途徑
只要api接口成功接到請求,就不能返回200以外的HTTP狀態。
為了保障前后端的數據交互的順暢,建議規范數據的返回,并采用固定的數據格式封裝。
接口返回模板:
{status:0,data:{}||[],msg:’’ }status: 接口的執行的狀態
> =0表示成功 <0 表示有異常 >0 表示接口有部分執行失敗Data 接口的主數據
可以根據實際返回數組或JSON對象
Msg
當status!=0 都應該有錯誤信息
開放接口供外部使用,需要關注接口運行的安全性,比如可以通過使用漏桶和令牌桶等算法來進行接口的限流、通過非對稱加密等方式來保護接口數據的安全性、通過使用時間戳加整個url簽名的方式來防止重放攻擊和進行限流保護。
對外提供的開放接口,需要進行參數有效性校驗。不合法入參的接口請求在校驗階段就應該返回了,不至于繼續操作后臺數據庫或其他數據存儲。
對外提供的開放接口,需要提供入參保護,包括檢查入參有效值的范圍、檢查入參落在白名單列表范圍、批量查詢操作的數據量范圍等。
后端接口開發中,使用類似于Swagger
、Api2Doc等接口管理工具,定義接口內容包含:接口名稱(name),接口地址(url),輸入參數(params),返回值(data),錯誤碼(errorCode),錯誤信息(errorMessage)。
由于實際業務開展過程中,可能會出現各種的api不是簡單的restful 規范能實現的,因此,需要有一些api突破restful規范原則。特別是移動互聯網的api設計,更需要有一些特定的api來優化數據請求的交互。
前后端分離后,接口所在域名和前端展示邏輯代碼不在一個域名,但由于瀏覽器同源策略限制,前端AJAX請求無法獲取數據,因此需要來解決跨域問題。
常見的跨越方案有JSONP,CORS, nginx或node代理跨域;jsonp的安全性會降低,nginx或node代理會增加api服務,CORS相對最容易,也比較安全;服務端設置Access-Control-Allow-Origin:*;如果接口需要讀取cookie的話,那么前端也需要做一些簡單的配置。
- java示例:
總結
- 上一篇: SSO单点登录和OAuth2.0的区别和
- 下一篇: 入职后,如何判断公司值不值得长期待下去?