Interface Specification separated front and rear ends

1 Introduction

With the rapid development of the Internet, showing the front pages, interactive experience more flexible, dazzling, in response to experience is increasingly demanding.

Required characteristics of high concurrent back-end services, high availability, high performance, scalability and so on has become even more demanding, thus leading to the front and rear ends of the respective research and development to focus on their areas of expertise Plow.

Yet another problem caused by: both the front and rear ends of the docking interface little attention, there is no agreement the interface specification in the case of dry their own, lead us to project the product development process, the interface FBI docking share the workload in the front and rear end 30% -50% or even higher.

FBI often butt end of the interface between the front and rear FBI and docking systems are the soft underbelly of the entire product research and development projects.

The main intention of this paper is to standardize agreed in advance to avoid unnecessary problems communicating FBI produced, so that everyone pleasant stay focus on their areas of expertise.

2. Why separation

Refer to two articles:

http://blog.jobbole.com/65509/
http://blog.jobbole.com/56161/

Development model currently available front and rear ends: "backend based MVC age", as shown below:

 

MVC-based back end of the era

Maintainability marked improvement, MVC is a very good cooperative mode, from the architectural level allows developers to know what code should be written in any place.

In order to make easier the View layer altogether, you can also choose Velocity, Freemaker and other templates, making the template can not write Java code.

Function appears weaker, but it is this limitation that the front and rear ends clearer division. However, it is still not clear, the typical problems of this stage are:

Front-end development of severe dependence development environment, the development of low efficiency.

In this architecture, the front and rear ends of collaboration has two modes:

One is to write front-end demo, written after, to make the back-end sets of templates.

Taobao is now still early, including a large number of business lines is this pattern.

The benefits are clear, demo locally developed very efficient.

Lack of back-end sets of templates is also needed, it is possible to set wrong, after also need to set the front end to determine the cost of back and forth communication adjustment is relatively large.

Another collaboration model is responsible for front-end browser-side View layer template development for all development and server-side, Alipay is this pattern.

UI benefits are related to the front-end code is like to write, do not be too concerned about the back-end, front-end development is the lack of binding heavy back-end environment, the environment has become an important factor affecting the efficiency of front-end development.

Duty front and rear end still tangled.

Velocity template is still pretty strong, variables, logic, macros, and other features, can still be achieved through a variety of business logic context variable to get.

In this way, a little weak as long as the front-end, back-end often will be asked to write a lot of business code in the template layer.

There is a big gray area is the Controller, page routing features such as front-end should be most concerned about, but it is implemented by the backend.

Controller and Model itself will often tangled, people looked the business code of teeth often occur in the Controller layer.

These problems can not all be attributed to the quality of programmers, or JSP enough.

Limitations on the front-end play.

Performance Optimization If you only do very limited space at the front, so we often need to cooperate in order to back-end collision sparks, but due to the back-end framework limitations, it is difficult to use Comet, Bigpipe and other technical solutions to optimize performance.

The total, just why code refactoring as:

• Separation of Concerns

• Segregation of Duties

• The right people do the right thing

• Better to build a model

• Rapid response changes

3. What is the separating

We now need to do before and after the separation of the first stage: "Based on Ajax brought SPA era", as shown:

 

Ajax-based era brought SPA

In this mode, the front and rear end of the division of labor is very clear, the key point of the front and rear end of the collaboration is Ajax interface.

It looks so wonderful, but looking back to look at it, which is not very different era JSP.

The complexity of the browser moved from the JSP server-side in the JavaScript, the browser becomes very complicated.

Similarly Spring MVC, this era began to emerge browser layered architecture:

 

Browser layered architecture

For this SPA stages, before and after the end of the separation has several important challenges:

Front and rear ends of the interface conventions.

If the backend interface mess, if the back-end business model is not stable enough, then the front-end development will be very painful. This one in the industry has agreed to API Blueprint and other programs and sediment interface == Ali, a lot of teams have a similar attempt, through the interface rules, interfaces, platforms and other ways to do it.

With rules and interfaces with the rear end of the precipitation it may also be used to simulate the data, so that the front and rear ends may be implemented efficiently in parallel development of the agreed interface.

== I believe this one will be better and better.

The complexity of the front-end development control.

Most SPA interactive applications to function based, JavaScript thousands of lines of code is too normal.

大量 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内容

• 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数据传输中一律使用字符串，具体日期格式因业务而定；

6. 未来的大前端

目前我们现在用的前后端分离模式属于第一阶段，由于使用到的一些技术jquery等，对于一些页面展示、数据渲染还是比较复杂，不能够很好的达到复用。对于前端还是有很大的工作量。

下一阶段可以在前端工程化方面，对技术框架的选择、前端模块化重用方面，可多做考量。

也就是要迎来“==前端为主的 MV* 时代==”。

大多数的公司也基本都处于这个分离阶段。

最后阶段就是==Node 带来的全栈时代==，完全有前端来控制页面，URL，Controller，路由等，后端的应用就逐步弱化为真正的数据服务+业务服务，做且仅能做的是提供数据、处理业务逻辑，关注高可用、高并发等。

这两个阶段仅做简单介绍，有兴趣的可以参考下面的资料。

7. 参考资料

https://www.zhihu.com/question/28207685
http://taobaofed.org/
http://2014.jsconf.cn/slides/herman-taobaoweb
http://blog.jobbole.com/65509/
https://blog.kaolafed.com/
http://blog.jobbole.com/65513/
http://blog.jobbole.com/65534/
http://blog.jobbole.com/65541/
http://blog.jobbole.com/56161/