前后端分離的接口規(guī)范
1. 前言
本文的主要初衷就是規(guī)范約定先行，盡量避免溝通聯(lián)調(diào)產(chǎn)生的不必要的問題，讓大家身心愉快地專注于各自擅長的領域。
2. 為何要分離
目前現(xiàn)有前后端開發(fā)模式：“后端為主的MVC時代”，如下圖所示：
后端為主的MVC時代
前端開發(fā)重度依賴開發(fā)環(huán)境，開發(fā)效率低?。這種架構下，前后端協(xié)作有兩種模式：一種是前端寫demo，寫好后，讓后端去套模板?。淘寶早期包括現(xiàn)在依舊有大量業(yè)務線是這種模式。好處很明顯，demo 可以本地開發(fā)，很高效。不足是還需要后端套模板，有可能套錯，套完后還需要前端確定，來回溝通調(diào)整的成本比較大。另一種協(xié)作模式是前端負責瀏覽器端的所有開發(fā)和服務器端的 View 層模板開發(fā)，支付寶是這種模式。?好處是 UI 相關的代碼都是前端去寫就好，后端不用太關注，不足就是前端開發(fā)重度綁定后端環(huán)境，環(huán)境成為影響前端開發(fā)效率的重要因素。 前后端職責依舊糾纏不清?。Velocity 模板還是蠻強大的，變量、邏輯、宏等特性，依舊可以通過拿到的上下文變量來實現(xiàn)各種業(yè)務邏輯。這樣，只要前端弱勢一點，往往就會被后端要求在模板層寫出不少業(yè)務代碼。還有一個很大的灰色地帶是 Controller，頁面路由等功能本應該是前端最關注的，但卻是由后端來實現(xiàn)?。Controller 本身與 Model 往往也會糾纏不清，看了讓人咬牙的業(yè)務代碼經(jīng)常會出現(xiàn)在 Controller 層。這些問題不能全歸結(jié)于程序員的素養(yǎng)，否則 JSP 就夠了。 對前端發(fā)揮的局限?。性能優(yōu)化如果只在前端做空間非常有限，于是我們經(jīng)常需要后端合作才能碰撞出火花，但由于后端框架限制，我們很難使用Comet、Bigpipe等技術方案來優(yōu)化性能。
3. 什么是分離
瀏覽器端的分層架構
前后端接口的約定。?如果后端的接口一塌糊涂，如果后端的業(yè)務模型不夠穩(wěn)定，那么前端開發(fā)會很痛苦。這一塊在業(yè)界有 API Blueprint 等方案來約定和沉淀接口，==在阿里，不少團隊也有類似嘗試，通過接口規(guī)則、接口平臺等方式來做。有了和后端一起沉淀的接口規(guī)則，還可以用來模擬數(shù)據(jù)，使得前后端可以在約定接口后實現(xiàn)高效并行開發(fā)。== 相信這一塊會越做越好。另外搜索公眾號互聯(lián)網(wǎng)架構師后臺回復“2T”，獲取一份驚喜禮包。 前端開發(fā)的復雜度控制。?SPA 應用大多以功能交互型為主，JavaScript 代碼過十萬行很正常。大量 JS 代碼的組織，與 View 層的綁定等，都不是容易的事情。典型的解決方案是業(yè)界的 Backbone，但 Backbone 做的事還很有限，依舊存在大量空白區(qū)域需要挑戰(zhàn)。
4. 如何做分離
4.1 職責分離
前后端僅僅通過異步接口(AJAX/JSONP)來編程 前后端都各自有自己的開發(fā)流程，構建工具，測試集合 關注點分離，前后端變得相對獨立并松耦合
4.2 開發(fā)流程
后端編寫和維護接口文檔，在 API 變化時更新接口文檔
后端根據(jù)接口文檔進行接口開發(fā) 前端根據(jù)接口文檔進行開發(fā) + Mock平臺 開發(fā)完成后聯(lián)調(diào)和提交測試
開發(fā)流程
4.3 具體實施
現(xiàn)在已基本完成了，接口方面的實施：
接口文檔服務器：可實現(xiàn)接口變更實時同步給前端展示；
接口規(guī)范定義：很重要，接口定義的好壞直接影響到前端的工作量和實現(xiàn)邏輯；具體定義規(guī)范見下節(jié)；
接口文檔+Mock平臺服務器
5. 接口規(guī)范V1.0.0
5.1 規(guī)范原則
5.2 基本格式
5.2.1 請求基本格式
GET請求、POST請求==必須包含key為body的入?yún)?，所有請求?shù)據(jù)包裝為JSON格式，并存放到入?yún)ody中==，示例如下：
GET請求：
xxx/login?body={"username":"admin","password":"123456","captcha":"scfd","rememberMe":1}
POST請求：
圖片 POST請求
5.2.2 響應基本格式
{
??code:?200,
??data:?{
????message:?"success"
??}
}
code : 請求處理狀態(tài)
data.message: 請求處理消息
code=200 且 data.message="success": 請求處理成功
code=200 且 data.message!="success": 請求處理成功, 普通消息提示：message內(nèi)容
code=500: 請求處理失敗，警告消息提示：message內(nèi)容
5.3 響應實體格式
{
??code:?200,
??data:?{
????message:?"success",
????entity:?{
??????id:?1,
??????name:?"XXX",
??????code:?"XXX"
????}
??}
}
5.4 響應列表格式
{
??code:?200,
??data:?{
????message:?"success",
????list:?[
??????{
????????id:?1,
????????name:?"XXX",
????????code:?"XXX"
??????},
??????{
????????id:?2,
????????name:?"XXX",
????????code:?"XXX"
??????}
????]
??}
}
data.list: 響應返回的列表數(shù)據(jù)
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
??}
}
5.6 特殊內(nèi)容規(guī)范
5.6.1 下拉框、復選框、單選框
{
??code:?200,
??data:?{
????message:?"success",
????list:?[
??????{
????????id:?1,
????????name:?"XXX",
????????code:?"XXX",
????????isSelect:?1
??????},
??????{
????????id:?1,
????????name:?"XXX",
????????code:?"XXX",
????????isSelect:?0
??????}
????]
??}
}
禁止下拉框、復選框、單選框判定選中邏輯由前端來處理，統(tǒng)一由后端邏輯判定選中返回給前端展示；
5.6.2 Boolean類型
關于Boolean類型，JSON數(shù)據(jù)傳輸中一律使用1/0來標示，1為是/True，0為否/False；
5.6.3 日期類型
關于日期類型，JSON數(shù)據(jù)傳輸中一律使用字符串，具體日期格式因業(yè)務而定；
6. 未來的大前端
相關閱讀：2T架構師學習資料干貨分享
全棧架構社區(qū)交流群
?「全棧架構社區(qū)」建立了讀者架構師交流群，大家可以添加小編微信進行加群。歡迎有想法、樂于分享的朋友們一起交流學習。
看完本文有收獲？請轉(zhuǎn)發(fā)分享給更多人
往期資源：