11.24 前後端分離必備的接口規範

作者 | 猿碼道

來源 | www.jianshu.com/p/c81008b68350

隨著互聯網的高速發展，前端頁面的展示、交互體驗越來越靈活、炫麗，響應體驗也要求越來越高，後端服務的高併發、高可用、高性能、高擴展等特性的要求也愈加苛刻，從而導致前後端研發各自專注於自己擅長的領域深耕細作。

然而帶來的另一個問題：前後端的對接界面雙方卻關注甚少，沒有任何接口約定規範情況下各自開發，導致我們在產品項目開發過程中，前後端的接口聯調對接
工作量佔比在30%-50%左右，甚至會更高。往往前後端接口聯調對接及系統間的聯調對接都是整個產品項目研發的軟肋。

本文的主要初衷就是規範約定先行，儘量避免溝通聯調產生的不必要的問題，讓大家身心愉快地專注於各自擅長的領域。

目前現有前後端開發模式：“後端為主的MVC時代”，如下圖所示：

後端為主的MVC時代

代碼可維護性得到明顯好轉，MVC 是個非常好的協作模式，從架構層面讓開發者懂得什麼代碼應該寫在什麼地方。為了讓 View 層更簡單幹脆，還可以選擇 Velocity、Freemaker 等模板，使得模板裡寫不了 Java 代碼。看起來是功能變弱了，但正是這種限制使得前後端分工更清晰。然而依舊並不是那麼清晰，這個階段的典型問題是：

1. 前端開發重度依賴開發環境，開發效率低。

這種架構下，前後端協作有兩種模式：

一種是前端寫demo，寫好後，讓後端去套模板。

淘寶早期包括現在依舊有大量業務線是這種模式。

好處很明顯，demo 可以本地開發，很高效。

不足是還需要後端套模板，有可能套錯，套完後還需要前端確定，來回溝通調整的成本比較大。

Tips：關注微信公眾號：Java後端，每日技術博文推送。

另一種協作模式是前端負責瀏覽器端的所有開發和服務器端的 View 層模板開發，支付寶是這種模式。好處是 UI 相關的代碼都是前端去寫就好，後端不用太關注，不足就是前端開發重度綁定後端環境，環境成為影響前端開發效率的重要因素。

2. 前後端職責依舊糾纏不清。

Velocity 模板還是蠻強大的，變量、邏輯、宏等特性，依舊可以通過拿到的上下文變量來實現各種業務邏輯。

這樣，只要前端弱勢一點，往往就會被後端要求在模板層寫出不少業務代碼。

還有一個很大的灰色地帶是 Controller，頁面路由等功能本應該是前端最關注的，但卻是由後端來實現。

Controller 本身與 Model 往往也會糾纏不清，看了讓人咬牙的業務代碼經常會出現在 Controller 層。

這些問題不能全歸結於程序員的素養，否則 JSP 就夠了。

3. 對前端發揮的侷限。

性能優化如果只在前端做空間非常有限，於是我們經常需要後端合作才能碰撞出火花，但由於後端框架限制，我們很難使用Comet、Bigpipe等技術方案來優化性能。

總上所述，就跟為什麼要代碼重構一樣：

1. 關注點分離

2. 職責分離

3. 對的人做對的事

4. 更好的共建模式

5. 快速的反應變化

我們現在要做的前後分離第一階段：“基於 Ajax 帶來的 SPA 時代”，如圖：

基於 Ajax 帶來的 SPA 時代這種模式下，前後端的分工非常清晰，前後端的關鍵協作點是 Ajax 接口。看起來是如此美妙，但回過頭來看看的話，這與 JSP 時代區別不大。複雜度從服務端的 JSP 裡移到了瀏覽器的 JavaScript，瀏覽器端變得很複雜。類似 Spring MVC，這個時代開始出現瀏覽器端的分層架構：

瀏覽器端的分層架構對於這一SPA階段，前後端分離有幾個重要挑戰：

1. 前後端接口的約定。

如果後端的接口一塌糊塗，如果後端的業務模型不夠穩定，那麼前端開發會很痛苦。這一塊在業界有 API Blueprint 等方案來約定和沉澱接口，==在阿里，不少團隊也有類似嘗試，通過接口規則、接口平臺等方式來做。有了和後端一起沉澱的接口規則，還可以用來模擬數據，使得前後端可以在約定接口後實現高效並行開發。== 相信這一塊會越做越好。

2. 前端開發的複雜度控制。SPA 應用大多以功能交互型為主，JavaScript 代碼過十萬行很正常。大量 JS 代碼的組織，與 View 層的綁定等，都不是容易的事情。典型的解決方案是業界的 Backbone，但 Backbone 做的事還很有限，依舊存在大量空白區域需要挑戰。

4.1 職責分離

職責分離

1. 前後端僅僅通過異步接口(AJAX/JSONP)來編程

2. 前後端都各自有自己的開發流程，構建工具，測試集合

3. 關注點分離，前後端變得相對獨立並松耦合

4.2 開發流程

1. 後端編寫和維護接口文檔，在 API 變化時更新接口文檔

2. 後端根據接口文檔進行接口開發

3. 前端根據接口文檔進行開發 + Mock平臺

4. 開發完成後聯調和提交測試

Mock 服務器根據接口文檔自動生成 Mock 數據，實現了接口文檔即API：

開發流程

4.3 具體實施

現在已基本完成了，接口方面的實施：1. 接口文檔服務器：可實現接口變更實時同步給前端展示；2. Mock接口數據平臺：可實現接口變更實時Mock數據給前端使用；3. 接口規範定義：很重要，接口定義的好壞直接影響到前端的工作量和實現邏輯；具體定義規範見下節；

接口文檔+Mock平臺服務器

5.1 規範原則

1. 接口返回數據即顯示：前端僅做渲染邏輯處理；

2. 渲染邏輯禁止跨多個接口調用；

3. 前端關注交互、渲染邏輯，儘量避免業務邏輯處理的出現；

4. 請求響應傳輸數據格式：JSON，JSON數據儘量簡單輕量，避免多級JSON的出現；

5.2 基本格式

5.2.1 請求基本格式

GET請求、POST請求==必須包含key為body的入參，所有請求數據包裝為JSON格式，並存放到入參body中==，示例如下：1. GET請求：

<code>xxx/login?body={"username":"admin","password":"123456","captcha":"scfd","rememberMe":1}/<code>

2. POST請求：

POST請求

5.2.2 響應基本格式

<code>{
 code: 200,
 data: {
 message: "success"
 }
}/<code>

1. code : 請求處理狀態200: 請求處理成功500: 請求處理失敗401: 請求未認證，跳轉登錄頁406: 請求未授權，跳轉未授權提示頁2. data.message: 請求處理消息code=200 且 data.message="success": 請求處理成功code=200 且 data.message!="success": 請求處理成功, 普通消息提示：message內容code=500: 請求處理失敗，警告消息提示：message內容

5.3 響應實體格式

<code>{
 code: 200,
 data: {
 message: "success",
 entity: {
 id: 1,
 name: "XXX",
 code: "XXX"
 }
 }
}/<code>

data.entity: 響應返回的實體數據

5.4 響應列表格式

<code>{
 code: 200,
 data: {
 message: "success",
 list: [
 {
 id: 1,
 name: "XXX",
 code: "XXX"
 },
 {
 id: 2,
 name: "XXX", 

 code: "XXX"
 }
 ]
 }
}/<code>

data.list: 響應返回的列表數據

5.5 響應分頁格式

<code>{
 code: 200,
 data: {
 recordCount: 2,
 message: "success",
 totalCount: 2,
 pageNo: 1,
 pageSize: 10,
 list: [
 {
 id: 1,
 name: "XXX",
 code: "H001"
 },
 {
 id: 2,
 name: "XXX",
 code: "H001"
 } ],
 totalPage: 1
 }
}/<code>

data.recordCount: 當前頁記錄數
data.totalCount: 總記錄數
data.pageNo: 當前頁碼
data.pageSize: 每頁大小
data.totalPage: 總頁數

5.6 特殊內容規範

5.6.1 下拉框、複選框、單選框

由後端接口統一邏輯判定是否選中，通過isSelect標示是否選中，示例如下：

<code>{
 code: 200,
 data: { 

 message: "success",
 list: [{
 id: 1,
 name: "XXX",
 code: "XXX",
 isSelect: 1
 }, {
 id: 1,
 name: "XXX",
 code: "XXX",
 isSelect: 0
 }]
 }
}/<code>

禁止下拉框、複選框、單選框判定選中邏輯由前端來處理，統一由後端邏輯判定選中返回給前端展示；

5.6.2 Boolean類型

關於Boolean類型，JSON數據傳輸中一律使用1/0來標示，1為是/True，0為否/False；

5.6.3 日期類型

關於日期類型，JSON數據傳輸中一律使用字符串，具體日期格式因業務而定；目前我們現在用的前後端分離模式屬於第一階段，由於使用到的一些技術jquery等，對於一些頁面展示、數據渲染還是比較複雜，不能夠很好的達到複用。對於前端還是有很大的工作量。下一階段可以在前端工程化方面，對技術框架的選擇、前端模塊化重用方面，可多做考量。也就是要迎來“==前端為主的 MV* 時代==”。大多數的公司也基本都處於這個分離階段。最後階段就是==Node 帶來的全棧時代==，完全有前端來控制頁面，URL，Controller，路由等，後端的應用就逐步弱化為真正的數據服務+業務服務，做且僅能做的是提供數據、處理業務邏輯，關注高可用、高併發等。

這兩個階段僅做簡單介紹，有興趣的可以參考下面的資料：

[1] https://www.zhihu.com/question/28207685

[2] http://taobaofed.org/

[3] http://2014.jsconf.cn/slides/herman-taobaoweb

[4] http://blog.jobbole.com/65509/

[5] https://github.com/CntChen/cntchen.github.io/issues/1

[6]https://blog.kaolafed.com/2017/05/11

[7]https://github.com/genify

[8]http://blog.jobbole.com/65513/

[9]http://blog.jobbole.com/65534/

[10]http://blog.jobbole.com/56161/、