接口仔也不是好当的，聊一聊前后端分离开发中后端接口设计规范

有的做 Java 的小伙伴会调侃自己是接口仔，不过老实说，接口仔也不是那么好当的，今天松哥就来和大家分享一篇前后端分离开发，后端接口设计规范的文章，希望能对各位小伙伴有所启发。另外再悄悄告诉大家，公众号后台回复 2TB 可以获取超 2TB 免费 Java 学习资源哦。

1. 前言

随着互联网的高速发展，前端页面的展示、交互体验越来越灵活、炫丽，响应体验也要求越来越高，后端服务的高并发、高可用、高性能、高扩展等特性的要求也愈加苛刻，从而导致前后端研发各自专注于自己擅长的领域深耕细作。

然而带来的另一个问题：前后端的对接界面双方却关注甚少，没有任何接口约定规范情况下各自干各自的，导致我们在产品项目开发过程中，前后端的接口联调对接工作量占比在 30%-50% 左右，甚至会更高。往往前后端接口联调对接及系统间的联调对接都是整个产品项目研发的软肋。

本文的主要初衷就是规范约定先行，尽量避免沟通联调产生的不必要的问题，让大家身心愉快地专注于各自擅长的领域。

2. 为何要分离

目前现有前后端开发模式：“后端为主的MVC时代”，如下图所示：

代码可维护性得到明显好转，MVC 是个非常好的协作模式，从架构层面让开发者懂得什么代码应该写在什么地方。为了让 View 层更简单干脆，还可以选择 Velocity、Freemaker 等模板，使得模板里写不了 Java 代码。

看起来是功能变弱了，但正是这种限制使得前后端分工更清晰。然而依旧并不是那么清晰，这个阶段的典型问题是：

1.前端开发重度依赖开发环境，开发效率低。

这种架构下，前后端协作有两种模式：一种是前端写 demo，写好后，让后端去套模板。淘宝早期包括现在依旧有大量业务线是这种模式。好处很明显，demo 可以本地开发，很高效。不足是还需要后端套模板，有可能套错，套完后还需要前端确定，来回沟通调整的成本比较大。

另一种协作模式是前端负责浏览器端的所有开发和服务器端的 View 层模板开发，支付宝是这种模式。好处是 UI 相关的代码都是前端去写就好，后端不用太关注，不足就是前端开发重度绑定后端环境，环境成为影响前端开发效率的重要因素。

2.前后端职责依旧纠缠不清。

Velocity 模板还是蛮强大的，变量、逻辑、宏等特性，依旧可以通过拿到的上下文变量来实现各种业务逻辑。这样，只要前端弱势一点，往往就会被后端要求在模板层写出不少业务代码。还有一个很大的灰色地带是 Controller，页面路由等功能本应该是前端最关注的，但却是由后端来实现。Controller 本身与 Model 往往也会纠缠不清，看了让人咬牙的业务代码经常会出现在 Controller 层。这些问题不能全归结于程序员的素养，否则 JSP 就够了。

3.对前端发挥的局限。

性能优化如果只在前端做空间非常有限，于是我们经常需要后端合作才能碰撞出火花，但由于后端框架限制，我们很难使用 Comet、Bigpipe 等技术方案来优化性能。

综上所述，就跟为什麽要代码重构一样：

3. 什么是分离

我们现在要做的前后分离第一阶段：“基于 Ajax 带来的 SPA 时代”，如图：

这种模式下，前后端的分工非常清晰，前后端的关键协作点是 Ajax 接口。看起来是如此美妙，但回过头来看看的话，这与 JSP 时代区别不大。复杂度从服务端的 JSP 里移到了浏览器的 JavaScript，浏览器端变得很复杂。类似 Spring MVC，这个时代开始出现浏览器端的分层架构：

对于这一 SPA 阶段，前后端分离有几个重要挑战：

1.前后端接口的约定。

如果后端的接口一塌糊涂，如果后端的业务模型不够稳定，那么前端开发会很痛苦。这一块在业界有 API Blueprint 等方案来约定和沉淀接口，在阿里，不少团队也有类似尝试，通过接口规则、接口平台等方式来做。有了和后端一起沉淀的接口规则，还可以用来模拟数据，使得前后端可以在约定接口后实现高效并行开发。相信这一块会越做越好。

2.前端开发的复杂度控制。

SPA 应用大多以功能交互型为主，JavaScript 代码过十万行很正常。大量 JS 代码的组织，与 View 层的绑定等，都不是容易的事情。典型的解决方案是业界的 Backbone，但 Backbone 做的事还很有限，依旧存在大量空白区域需要挑战。

4. 如何做分离

4.1 职责分离

4.2 开发流程

Mock 服务器根据接口文档自动生成 Mock 数据，实现了接口文档即API：

4.3 具体实施

现在已基本完成了，接口方面的实施：

5. 接口规范 V1.0.0

5.1 规范原则

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 : 请求处理状态

data.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
    }
}

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