聊聊前后端分离接⼝规范
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阶段，前后端分离有⼏个重要挑战：
jsp用什么前端框架前后端接⼝的约定。
如果后端的接⼝⼀塌糊涂，如果后端的业务模型不够稳定，那么前端开发会很痛苦。这⼀块在业界有 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的出现；
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: 请求未授权，跳转未授权提⽰页
code=200 且 ssage="success": 请求处理成功
code=200 且 ssage!="success": 请求处理成功, 普通消息提⽰：message内容
code=500: 请求处理失败，警告消息提⽰：message内容
5.3 响应实体格式
{
code: 200,
data: {
message: "success",
entity: {
id: 1,
name: "XXX",
code: "XXX"
}
}
}
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.pageNo: 当前页码
data.pageSize: 每页⼤⼩
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
}]
}
}

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。