1 背景
此處我不解釋為什么要前后端分離、前后端分離的優缺點等問題,采用前后端分離開發模式就變成了這樣,
前后端分離的開發模式引入的一個問題就是對接界面雙方卻關注甚少,沒有任何接口規范情況下各自擼起袖子就是干,
導致我們在產品項目開發過程中,前后端的接口聯調對接工作量占比在30%-50%左右,甚至會更高。往往前后端接口聯調對接及系統間的聯調對接都是整個產品項目研發的軟肋。
本文的主要初衷就是規范約定先行,盡量避免溝通聯調產生的不必要的問題,讓大家身心愉快地專注于各自擅長的領域。
2 接口規范
2.1 原則
前端關注交互、渲染邏輯,盡量避免業務邏輯處理;后端關注數據、邏輯等。
渲染邏輯禁止跨多個接口調用。
2.2 通信協議
使用HTTPs協議或者HTTP協議,統一用一種,建議使用HTTPs協議以確保交互數據的傳輸安全。
2.3 域名
盡量將API部署在專用域名之下,如https://api.xxx.com;多個項目創建API,用項目名作為文件夾,如https://api.xxx.com/project-name。
2.4 URL
建議全部使用小寫,不用大寫
如https://api.xxx.com/project-name/v1/users/。
用中杠-不用下杠_
如https://api.xxx.com/project-name/v1/users/。
URL中的名詞表示資源集合,使用復數形式
如https://api.xxx.com/project-name/v1/users/,如users。關于復數的問題社區內爭議很久了,再加上一些不規則的名次復數問題,就更不好統一了。如people、foot、hero,不是簡單的加s就可以了。
避免層級過深的URL
體現API演進即攜帶版本信息
如https://api.xxx.com/project-name/v1/users/,v1即版本信息。
只能有名詞,不能有動詞
在RESTful架構中,每個網址代表一種資源(resource),所以網址中不能有動詞,只能有名詞,而且所用的名詞往往與數據庫的表格名對應,正例如https://api.xxx.com/project-name/v1/students;反例如https://api.xxx.com/project-name/v1/getStudents。
2.5 正確使用HTTP動詞
GET
冪等的操作,對應查詢功能,響應的數據可以是單個的,也可以是多個的。所謂冪等即一個方法重復執行多次,產生的效果是一樣的。如GET /api/v1/users/,GET /api/v1/users/1。
POST
非冪等的操作,用來創建一個子資源。如POST /api/v1/users,會在users下面創建一個user;多次執行,將導致多條相同的用戶被創建。
PUT
冪等的操作,用來替換(新增或者更新)一個資源。如PUT /api/v1/users/1的意思是替換 /users/1,如果已經存在就替換沒有就新增。
PATCH
冪等的操作,用來對已知資源進行"局部更新"。
DELETE
冪等的操作,用來刪除一個資源。如DELETE /api/v1/users/1的意思是刪除id為1的用戶。
2.6 響應格式
rest接口響應數據中應該包含響應狀態和響應數據,數據格式為json。響應數據格式大致為
{
code:200|500,
msg:成功|失敗|異常,
data:響應數據
}
單一數據時格式為
{
code:200|500,
msg:成功|失敗|異常,
data:{
key1:value1,
key2:value2,
......
}
}
列表數據時格式為
{
code:200|500,
msg:成功|失敗|異常,
data:[{
key1:value1,
key2:value2,
......
},]
}
分頁數據時格式為
{
code:200|500,
msg:成功|失敗|異常,
data:{
pageNum: 1,//當前頁碼即第幾頁,從1開始
pageSize: 10,//每頁的行數
total: 324,//符合查詢條件的記錄數
pages: 33//總頁數
list: [{
key1:value1,
key2:value2,
......
},]
}
}
2.7 數據類型
這里特別說明Boolean類型和日期類型,其他類型正常使用即可。關于Boolean類型,JSON數據傳輸中建議統一使用1/0來標示即1為True0為False;日期類型JSON數據傳輸中建議使用數字類型即時間戳,具體日期格式可因業務而定。
2.8 異步任務
對耗時的異步任務,服務器端接受客戶端傳遞的參數后,應返回創建成功的任務資源,其中包含了任務的執行狀態。客戶端可以輪訓該任務獲得最新的執行進度。關于長耗時任務的處理可參考我的另外一篇文章長耗時任務的善后處理。
2.9 錯誤處理
對于非正常情況,如未授權、沒有權限、請求的資源不存在、參數錯誤等,都應有相應的錯誤提示,方便接口調用者根據提示改正錯誤。
正例
{
code:400,
msg:請求的資源不存在,
data:{}
}
反例
0
2.10 URI失效
隨著系統發展,總有一些API失效或者遷移,對失效的API,返回404 not found 或 410 gone;對遷移的API,返回 301 重定向。
3 最后
沒有規矩不成方圓,有了規矩不遵守那規矩就形同虛設。希望大家在今后的開發中努力遵守規范,減少因接口不規范帶來的麻煩,提高工作效率。