前后端分離必備的介面規范，十分接地氣！

作者：猿碼道
https://www.jianshu.com/p/c81008b68350

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 寫了一段邏輯，同事直呼看不懂，你試試看，，

4.吊打 Tomcat ，Undertow 性能很炸！！

5.《Java開發手冊（嵩山版）》最新發布，速速下載！

覺得不錯，別忘了隨手點贊+轉發哦！

標籤：Java

上一篇：java字串常用方法

下一篇：Java基礎之：包裝類(Wrapper)