前后端分離的接口規(guī)范

2. 為何要分離

1. 前端開(kāi)發(fā)重度依賴開(kāi)發(fā)環(huán)境，開(kāi)發(fā)效率低 。這種架構(gòu)下，前后端協(xié)作有兩種模式：一種是前端寫(xiě)demo，寫(xiě)好后，讓后端去套模板 。淘寶早期包括現(xiàn)在依舊有大量業(yè)務(wù)線是這種模式。好處很明顯，demo 可以本地開(kāi)發(fā)，很高效。不足是還需要后端套模板，有可能套錯(cuò)，套完后還需要前端確定，來(lái)回溝通調(diào)整的成本比較大。另一種協(xié)作模式是前端負(fù)責(zé)瀏覽器端的所有開(kāi)發(fā)和服務(wù)器端的 View 層模板開(kāi)發(fā)，支付寶是這種模式。 好處是 UI 相關(guān)的代碼都是前端去寫(xiě)就好，后端不用太關(guān)注，不足就是前端開(kāi)發(fā)重度綁定后端環(huán)境，環(huán)境成為影響前端開(kāi)發(fā)效率的重要因素。

2. 前后端職責(zé)依舊糾纏不清 。Velocity 模板還是蠻強(qiáng)大的，變量、邏輯、宏等特性，依舊可以通過(guò)拿到的上下文變量來(lái)實(shí)現(xiàn)各種業(yè)務(wù)邏輯。這樣，只要前端弱勢(shì)一點(diǎn)，往往就會(huì)被后端要求在模板層寫(xiě)出不少業(yè)務(wù)代碼。還有一個(gè)很大的灰色地帶是 Controller，頁(yè)面路由等功能本應(yīng)該是前端最關(guān)注的，但卻是由后端來(lái)實(shí)現(xiàn) 。Controller 本身與 Model 往往也會(huì)糾纏不清，看了讓人咬牙的業(yè)務(wù)代碼經(jīng)常會(huì)出現(xiàn)在 Controller 層。這些問(wèn)題不能全歸結(jié)于程序員的素養(yǎng)，否則 JSP 就夠了。

3. 對(duì)前端發(fā)揮的局限 。性能優(yōu)化如果只在前端做空間非常有限，于是我們經(jīng)常需要后端合作才能碰撞出火花，但由于后端框架限制，我們很難使用Comet、Bigpipe等技術(shù)方案來(lái)優(yōu)化性能。

1. 關(guān)注點(diǎn)分離
2. 職責(zé)分離
3. 對(duì)的人做對(duì)的事
4. 更好的共建模式
5. 快速的反應(yīng)變化

3. 什么是分離

1. 前后端接口的約定。 如果后端的接口一塌糊涂，如果后端的業(yè)務(wù)模型不夠穩(wěn)定，那么前端開(kāi)發(fā)會(huì)很痛苦。這一塊在業(yè)界有 API Blueprint 等方案來(lái)約定和沉淀接口，==在阿里，不少團(tuán)隊(duì)也有類似嘗試，通過(guò)接口規(guī)則、接口平臺(tái)等方式來(lái)做。有了和后端一起沉淀的接口規(guī)則，還可以用來(lái)模擬數(shù)據(jù)，使得前后端可以在約定接口后實(shí)現(xiàn)高效并行開(kāi)發(fā)。== 相信這一塊會(huì)越做越好。

2. 前端開(kāi)發(fā)的復(fù)雜度控制。 SPA 應(yīng)用大多以功能交互型為主，JavaScript 代碼過(guò)十萬(wàn)行很正常。大量 JS 代碼的組織，與 View 層的綁定等，都不是容易的事情。典型的解決方案是業(yè)界的 Backbone，但 Backbone 做的事還很有限，依舊存在大量空白區(qū)域需要挑戰(zhàn)。

4. 如何做分離

4.1 職責(zé)分離

1. 前后端僅僅通過(guò)異步接口(AJAX/JSONP)來(lái)編程

2. 前后端都各自有自己的開(kāi)發(fā)流程，構(gòu)建工具，測(cè)試集合

3. 關(guān)注點(diǎn)分離，前后端變得相對(duì)獨(dú)立并松耦合

4.2 開(kāi)發(fā)流程

1. 后端編寫(xiě)和維護(hù)接口文檔，在 API 變化時(shí)更新接口文檔

2. 后端根據(jù)接口文檔進(jìn)行接口開(kāi)發(fā)

3. 前端根據(jù)接口文檔進(jìn)行開(kāi)發(fā) + Mock平臺(tái)

4. 開(kāi)發(fā)完成后聯(lián)調(diào)和提交測(cè)試

4.3 具體實(shí)施

1. 接口文檔服務(wù)器：可實(shí)現(xiàn)接口變更實(shí)時(shí)同步給前端展示；

2. Mock接口數(shù)據(jù)平臺(tái)：可實(shí)現(xiàn)接口變更實(shí)時(shí)Mock數(shù)據(jù)給前端使用；

3. 接口規(guī)范定義：很重要，接口定義的好壞直接影響到前端的工作量和實(shí)現(xiàn)邏輯；具體定義規(guī)范見(jiàn)下節(jié)；

5. 接口規(guī)范V1.0.0

5.1 規(guī)范原則

1. 接口返回?cái)?shù)據(jù)即顯示：前端僅做渲染邏輯處理；

2. 渲染邏輯禁止跨多個(gè)接口調(diào)用；

3. 前端關(guān)注交互、渲染邏輯，盡量避免業(yè)務(wù)邏輯處理的出現(xiàn)；

4. 請(qǐng)求響應(yīng)傳輸數(shù)據(jù)格式：JSON，JSON數(shù)據(jù)盡量簡(jiǎn)單輕量，避免多級(jí)JSON的出現(xiàn)；

5.2 基本格式

5.2.1 請(qǐng)求基本格式

1. GET請(qǐng)求：

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

1. POST請(qǐng)求：

   
   

   

   
   

   POST請(qǐng)求

5.2.2 響應(yīng)基本格式

{
  code: 200,
  data: {
    message: "success"
  }
}

1. code : 請(qǐng)求處理狀態(tài)

200: 請(qǐng)求處理成功

500: 請(qǐng)求處理失敗

401: 請(qǐng)求未認(rèn)證，跳轉(zhuǎn)登錄頁(yè)

406: 請(qǐng)求未授權(quán)，跳轉(zhuǎn)未授權(quán)提示頁(yè)

1. data.message: 請(qǐng)求處理消息

code=200 且 data.message="success": 請(qǐng)求處理成功

code=200 且 data.message!="success": 請(qǐng)求處理成功, 普通消息提示：message內(nèi)容

code=500: 請(qǐng)求處理失敗，警告消息提示：message內(nèi)容

5.3 響應(yīng)實(shí)體格式

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

data.entity: 響應(yīng)返回的實(shí)體數(shù)據(jù)

5.4 響應(yīng)列表格式

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

data.list: 響應(yīng)返回的列表數(shù)據(jù)

5.5 響應(yīng)分頁(yè)格式

{
  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: 當(dāng)前頁(yè)記錄數(shù) data.totalCount: 總記錄數(shù) data.pageNo: 當(dāng)前頁(yè)碼 data.pageSize: 每頁(yè)大小 data.totalPage: 總頁(yè)數(shù)。

5.6 特殊內(nèi)容規(guī)范

5.6.1 下拉框、復(fù)選框、單選框

{
  code: 200,
  data: {
    message: "success",
    list: [
      {
        id: 1,
        name: "XXX",
        code: "XXX",
        isSelect: 1
      },
      {
        id: 1,
        name: "XXX",
        code: "XXX",
        isSelect: 0
      }
    ]
  }
}

禁止下拉框、復(fù)選框、單選框判定選中邏輯由前端來(lái)處理，統(tǒng)一由后端邏輯判定選中返回給前端展示；

5.6.2 Boolean類型

關(guān)于Boolean類型，JSON數(shù)據(jù)傳輸中一律使用1/0來(lái)標(biāo)示，1為是/True，0為否/False；

5.6.3 日期類型

關(guān)于日期類型，JSON數(shù)據(jù)傳輸中一律使用字符串，具體日期格式因業(yè)務(wù)而定；

6. 未來(lái)的大前端