前後端分離必備的介面規範，十分接地氣！
1. 前言
隨著網際網路的高速發展，前端頁面的展示、互動體驗越來越靈活、炫麗，響應體驗也要求越來越高，後端服務的高併發、高可用、高效能、高擴充套件等特性的要求也愈加苛刻，從而導致前後端研發各自專注於自己擅長的領域深耕細作。
然而帶來的另一個問題：前後端的對接介面雙方卻關注甚少，沒有任何介面約定規範情況下各自幹各自的，導致我們在產品專案開發過程中，前後端的介面聯調對接工作量佔比在30%-50%左右，甚至會更高。往往前後端介面聯調對接及系統間的聯調對接都是整個產品專案研發的軟肋。
本文的主要初衷就是規範約定先行，儘量避免溝通聯調產生的不必要的問題，讓大家身心愉快地專注於各自擅長的領域。
2. 為何要分離
目前現有前後端開發模式：“後端為主的MVC時代”，如下圖所示：
後端為主的MVC時代
程式碼可維護性得到明顯好轉，MVC 是個非常好的協作模式，從架構層面讓開發者懂得什麼程式碼應該寫在什麼地方。為了讓 View 層更簡單幹脆，還可以選擇 Velocity、Freemaker 等模板，使得模板裡寫不了 Java 程式碼。
看起來是功能變弱了，但正是這種限制使得前後端分工更清晰。然而依舊並不是那麼清晰，這個階段的典型問題是：
前端開發重度依賴開發環境，開發效率低。
這種架構下，前後端協作有兩種模式：一種是前端寫demo，寫好後，讓後端去套模板 。淘寶早期包括現在依舊有大量業務線是這種模式。好處很明顯，demo 可以本地開發，很高效。不足是還需要後端套模板，有可能套錯，套完後還需要前端確定，來回溝通調整的成本比較大。
另一種協作模式是前端負責瀏覽器端的所有開發和伺服器端的 View 層模板開發，支付寶是這種模式。好處是 UI 相關的程式碼都是前端去寫就好，後端不用太關注，不足就是前端開發重度繫結後端環境，環境成為影響前端開發效率的重要因素。
前後端職責依舊糾纏不清。
Velocity 模板還是蠻強大的，變數、邏輯、巨集等特性，依舊可以通過拿到的上下文變數來實現各種業務邏輯。這樣，只要前端弱勢一點，往往就會被後端要求在模板層寫出不少業務程式碼。
還有一個很大的灰色地帶是 Controller，頁面路由等功能本應該是前端最關注的，但卻是由後端來實現。Controller 本身與 Model 往往也會糾纏不清，看了讓人咬牙的業務程式碼經常會出現在 Controller 層。這些問題不能全歸結於程式設計師的素養，否則 JSP 就夠了。
對前端發揮的侷限。
效能優化如果只在前端做空間非常有限，於是我們經常需要後端合作才能碰撞出火花，但由於後端框架限制，我們很難使用Comet、Bigpipe等技術方案來優化效能。
總上所述，就跟為什麼要程式碼重構一樣：
-
關注點分離
-
職責分離
-
對的人做對的事
-
更好的共建模式
-
快速的反應變化
3. 什麼是分離
我們現在要做的前後分離第一階段：“基於 Ajax 帶來的 SPA 時代”，如圖：
基於 Ajax 帶來的 SPA 時代
這種模式下，前後端的分工非常清晰，前後端的關鍵協作點是 Ajax 介面。看起來是如此美妙，但回過頭來看看的話，這與 JSP 時代區別不大。複雜度從服務端的 JSP 裡移到了瀏覽器的 JavaScript，瀏覽器端變得很複雜。類似 Spring MVC，這個時代開始出現瀏覽器端的分層架構：
瀏覽器端的分層架構
對於這一SPA階段，前後端分離有幾個重要挑戰：
前後端介面的約定。
如果後端的介面一塌糊塗，如果後端的業務模型不夠穩定，那麼前端開發會很痛苦。這一塊在業界有 API Blueprint 等方案來約定和沉澱介面，在阿里，不少團隊也有類似嘗試，通過介面規則、介面平臺等方式來做。有了和後端一起沉澱的介面規則，還可以用來模擬資料，使得前後端可以在約定介面後實現高效並行開發。 相信這一塊會越做越好。
前端開發的複雜度控制。
SPA 應用大多以功能互動型為主，JavaScript 程式碼過十萬行很正常。大量 JS 程式碼的組織，與 View 層的繫結等，都不是容易的事情。典型的解決方案是業界的 Backbone，但 Backbone 做的事還很有限，依舊存在大量空白區域需要挑戰。
4. 如何做分離
4.1 職責分離
職責分離
-
前後端僅僅通過非同步介面(AJAX/JSONP)來程式設計
-
前後端都各自有自己的開發流程，構建工具，測試集合
-
關注點分離，前後端變得相對獨立並鬆耦合
4.2 開發流程
-
後端編寫和維護介面文件，在 API 變化時更新介面文件
-
後端根據介面文件進行介面開發
-
前端根據介面文件進行開發 + Mock平臺
-
開發完成後聯調和提交測試
Mock 伺服器根據介面文件自動生成 Mock 資料，實現了介面文件即API：
開發流程
4.3 具體實施
現在已基本完成了，介面方面的實施：
-
介面文件伺服器：可實現介面變更實時同步給前端展示；
-
Mock介面資料平臺：可實現介面變更實時Mock資料給前端使用；
-
介面規範定義：很重要，介面定義的好壞直接影響到前端的工作量和實現邏輯；具體定義規範見下節；
介面文件+Mock平臺伺服器
5. 介面規範V1.0.0
5.1 規範原則
-
介面返回資料即顯示：前端僅做渲染邏輯處理；
-
渲染邏輯禁止跨多個介面呼叫；
-
前端關注互動、渲染邏輯，儘量避免業務邏輯處理的出現；
-
請求響應傳輸資料格式：JSON，JSON資料儘量簡單輕量，避免多級JSON的出現；
5.2 基本格式
5.2.1 請求基本格式
GET請求、POST請求必須包含key為body的入參，所有請求資料包裝為JSON格式，並存放到入參body中，示例如下：
GET請求：
xxx/login?body={"username":"admin","password":"123456","captcha":"scfd","rememberMe":1}
POST請求：
5.2.2 響應基本格式
{
code:200,
data:{
message:"success"
}
}
code : 請求處理狀態
-
200: 請求處理成功
-
500: 請求處理失敗
-
401: 請求未認證，跳轉登入頁
-
406: 請求未授權，跳轉未授權提示頁
data.message: 請求處理訊息
-
code=200 且 data.message="success": 請求處理成功
-
code=200 且 data.message!="success": 請求處理成功, 普通訊息提示：message內容。推薦：兩張趣圖助你理解 HTTP 狀態碼。
-
code=500: 請求處理失敗，警告訊息提示：message內容
5.3 響應實體格式
{
code:200,
data:{
message:"success",
entity:{
id:1,
name:"XXX",
code:"XXX"
}
}
}
data.entity: 響應返回的實體資料
5.4 響應列表格式
data.list: 響應返回的列表資料
5.5 響應分頁格式
{
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
}
}
-
data.recordCount: 當前頁記錄數
-
data.totalCount: 總記錄數
-
data.pageNo: 當前頁碼
-
data.pageSize: 每頁大小
-
data.totalPage: 總頁數
5.6 特殊內容規範
5.6.1 下拉框、複選框、單選框
由後端介面統一邏輯判定是否選中，通過isSelect標示是否選中，示例如下：
{
code:200,
data:{
message:"success",
list:\[{
id:1,
name:"XXX",
code:"XXX",
isSelect:1
},{
id:1,
name:"XXX",
code:"XXX",
isSelect:0
}\]
}
}
禁止下拉框、複選框、單選框判定選中邏輯由前端來處理，統一由後端邏輯判定選中返回給前端展示；
5.6.2 Boolean型別
關於Boolean型別，JSON資料傳輸中一律使用1/0來標示，1為是/True，0為否/False；
5.6.3 日期型別
關於日期型別，JSON資料傳輸中一律使用字串，具體日期格式因業務而定；推薦：JSON是什麼，為什麼這麼流行？
6. 未來的大前端
目前我們現在用的前後端分離模式屬於第一階段，由於使用到的一些技術jquery等，對於一些頁面展示、資料渲染還是比較複雜，不能夠很好的達到複用。對於前端還是有很大的工作量。
下一階段可以在前端工程化方面，對技術框架的選擇、前端模組化重用方面，可多做考量。也就是要迎來“前端為主的 MV* 時代”。大多數的公司也基本都處於這個分離階段。
最後階段就是Node 帶來的全棧時代，完全有前端來控制頁面，URL，Controller，路由等，後端的應用就逐步弱化為真正的資料服務+業務服務，做且僅能做的是提供資料、處理業務邏輯，關注高可用、高併發等。
近期熱文推薦：
1.Java 15 正式釋出， 14 個新特性，重新整理你的認知！！
2.終於靠開源專案弄到 IntelliJ IDEA 啟用碼了，真香！
3.我用 Java 8 寫了一段邏輯，同事直呼看不懂，你試試看。。
覺得不錯，別忘了隨手點贊+轉發哦！