前后端分離開發模式下的接口規范

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 最后

沒有規矩不成方圓,有了規矩不遵守那規矩就形同虛設。希望大家在今后的開發中努力遵守規范,減少因接口不規范帶來的麻煩,提高工作效率。

?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發布,文章內容僅代表作者本人觀點,簡書系信息發布平臺,僅提供信息存儲服務。
  • 序言:七十年代末,一起剝皮案震驚了整個濱河市,隨后出現的幾起案子,更是在濱河造成了極大的恐慌,老刑警劉巖,帶你破解...
    沈念sama閱讀 229,001評論 6 537
  • 序言:濱河連續發生了三起死亡事件,死亡現場離奇詭異,居然都是意外死亡,警方通過查閱死者的電腦和手機,發現死者居然都...
    沈念sama閱讀 98,786評論 3 423
  • 文/潘曉璐 我一進店門,熙熙樓的掌柜王于貴愁眉苦臉地迎上來,“玉大人,你說我怎么就攤上這事。” “怎么了?”我有些...
    開封第一講書人閱讀 176,986評論 0 381
  • 文/不壞的土叔 我叫張陵,是天一觀的道長。 經常有香客問我,道長,這世上最難降的妖魔是什么? 我笑而不...
    開封第一講書人閱讀 63,204評論 1 315
  • 正文 為了忘掉前任,我火速辦了婚禮,結果婚禮上,老公的妹妹穿的比我還像新娘。我一直安慰自己,他們只是感情好,可當我...
    茶點故事閱讀 71,964評論 6 410
  • 文/花漫 我一把揭開白布。 她就那樣靜靜地躺著,像睡著了一般。 火紅的嫁衣襯著肌膚如雪。 梳的紋絲不亂的頭發上,一...
    開封第一講書人閱讀 55,354評論 1 324
  • 那天,我揣著相機與錄音,去河邊找鬼。 笑死,一個胖子當著我的面吹牛,可吹牛的內容都是我干的。 我是一名探鬼主播,決...
    沈念sama閱讀 43,410評論 3 444
  • 文/蒼蘭香墨 我猛地睜開眼,長吁一口氣:“原來是場噩夢啊……” “哼!你這毒婦竟也來了?” 一聲冷哼從身側響起,我...
    開封第一講書人閱讀 42,554評論 0 289
  • 序言:老撾萬榮一對情侶失蹤,失蹤者是張志新(化名)和其女友劉穎,沒想到半個月后,有當地人在樹林里發現了一具尸體,經...
    沈念sama閱讀 49,106評論 1 335
  • 正文 獨居荒郊野嶺守林人離奇死亡,尸身上長有42處帶血的膿包…… 初始之章·張勛 以下內容為張勛視角 年9月15日...
    茶點故事閱讀 40,918評論 3 356
  • 正文 我和宋清朗相戀三年,在試婚紗的時候發現自己被綠了。 大學時的朋友給我發了我未婚夫和他白月光在一起吃飯的照片。...
    茶點故事閱讀 43,093評論 1 371
  • 序言:一個原本活蹦亂跳的男人離奇死亡,死狀恐怖,靈堂內的尸體忽然破棺而出,到底是詐尸還是另有隱情,我是刑警寧澤,帶...
    沈念sama閱讀 38,648評論 5 362
  • 正文 年R本政府宣布,位于F島的核電站,受9級特大地震影響,放射性物質發生泄漏。R本人自食惡果不足惜,卻給世界環境...
    茶點故事閱讀 44,342評論 3 347
  • 文/蒙蒙 一、第九天 我趴在偏房一處隱蔽的房頂上張望。 院中可真熱鬧,春花似錦、人聲如沸。這莊子的主人今日做“春日...
    開封第一講書人閱讀 34,755評論 0 28
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽。三九已至,卻和暖如春,著一層夾襖步出監牢的瞬間,已是汗流浹背。 一陣腳步聲響...
    開封第一講書人閱讀 36,009評論 1 289
  • 我被黑心中介騙來泰國打工, 沒想到剛下飛機就差點兒被人妖公主榨干…… 1. 我叫王不留,地道東北人。 一個月前我還...
    沈念sama閱讀 51,839評論 3 395
  • 正文 我出身青樓,卻偏偏與公主長得像,于是被迫代替她去往敵國和親。 傳聞我的和親對象是個殘疾皇子,可洞房花燭夜當晚...
    茶點故事閱讀 48,107評論 2 375

推薦閱讀更多精彩內容