后端API接口

在一个新型的web应用中，由于中台只负责数据的输送，不涉及具体业务，所以就需要搭建一个业务服务来组装业务数据，把 浏览器/客户端 和中台连接起来。业务服务将组装完的数据以统一的数据格式返回给客户端，这里就需要对业务服务后台接口进行统一设计。下面就来具体介绍一下如何设计和编写后端接口。
0 统一规范
0.1 理清业务流程
通过需求文档，描述清楚业务流程，定义好相关的设计规范。根据项目大小划分好前台和后台的功能需求，通过需求来得到对应的模块。

0.2 定义前后端开发的接口规范
一般前后端分离项目会拥有不同的数据格式，例如 json、url等。 这里要通过文档的形式同前后端一起确定好数据阐述的格式。

接口地址：不包含接口BASE地址。

请求方式: get、post、put、delete等。

请求参数：数据格式（默认json）、数据类型、是否必填、中文描述。

响应参数：类型、中文描述。

0.3 定义接口文档
这里的接口文档一般就是对应后台的实体，即RequestVo（调用后台接口访问的实体）和给往前端的ResponseVo（前台调用接口时前往的实体）。一般来说ResponseVo都会在后台做一个统一的处理为ResultVo。

对于ResultVo的规范需要在上一节中定义好，例如：错误码Code，错误描述msg，请求的url，以及实体泛型T。

需要注意的是，这里定义的接口文档实在彻底了解号数据流、业务流的基础之上完成的。

尽量采用自动化接口文档，可以做到在线测试，同步更新。 文档中应包含：接口BASE地址、接口版本、接口模块分类等。

有了这个接口文档之后（实质上就是定义实体的过程和对应的json），前后端的开发基本根据这个文档去开发。在实际的项目业务中，接口文档会产生版本的迭代，这个时候我们会需要将它放到版本管理器中，不论你用的是git亦或者是svn。

注：除了以上描述的，我们的项目中还有redis，mongoDB，elasticsearch等。这些都是在非常了解业务的状况和系统架构下去设计的。后台运用这些工具去完成接口功能的实现以及系统功能和性能的实现。

1 后端接口编写
主要是对RESTful接口设计做一个介绍。

1.0 后端接口介绍
1.0.1 接口交互
前端和后端进行交互，前端按照约定请求URL路径，并传入相关参数，后端服务器接收
请求，进行业务处理，返回数据给前端。

针对URL路径的restful风格，以及传入参数的公共请求头的要求（如：app_version,api_version,device等)，这里就不介绍了,小伙伴们可以自行去了解，也比较简单。

1.0.2 返回格式
在 0.2小节 中我们提到了会把ResponseVo 处理为一个统一的ResultVo。

这个ResultVo大致由4个部分组成，分别 是接口请求地址（url）、接口请求方式（get/post）、请求数据（request）、响应数据（response）。

在前端的眼中，拿到的数据就会长这样，也就是我们所理解的返回格式。

一般来说没有明确的规范要求，具体是看开发时需要什么就添加什么。

例如，我们要提示前端用户权限不足，那么我们返回的状态码就可以定义为 403 ；如果我们要告诉前端的数据参数异常，我们就可以把返回的状态码定义成 102 。具体的状态码细节可以参考http请求返回的状态码。

全局异常处理
如果我们接口向上一节那么写，就会发现这样就把所有的问题都响应到前端了，解决这个问题的办法就是使用全局异常处理。

由于参数校验会自动引发异常，我们就不用再去手动捕捉异常进行处理，这个时候我们就可以用spring boot全局异常处理。

首先，我们需要新建一个ExceptionControllerAdvice类，在这个类上加上**@ControllerAdvice或@RestControllerAdvice注解**，这个类就配置成全局处理类了。（这个根据你的Controller层用的是@Controller还是@RestController来决定）

然后在类中新建方法，在方法上加上**@ExceptionHandler注解**并指定你想处理的异常类型，接着在方法内编写对该异常的操作逻辑，就完成了对该异常的全局处理。

自定义统一响应体

统一数据响应第一步肯定要做的就是我们自己自定义一个响应体类，无论后台是运行正常还是发生异常，响应给前端的数据格式是不变的。

响应码枚举

要规范响应体中的响应码和响应信息我们使用枚举是最好的。Java中自带了枚举类型，我们可以依据枚举类型创建一个响应码枚举类。

全局处理响应数据
既然我们对响应数据做了处理，也对异常做了统一返回响应体，我们可以用一个全局处理来把省略掉用响应体包装接口返回数据。

我们同样是像全局异常处理一样，定义一个全局处理类 ResponseControllerAdvice 继承 ResponseBodyAdvice 接口并重写其中的方法。

重写的这两个方法是用来在controller将数据进行返回前进行增强操作，supports方法要返回为true才会执行beforeBodyWrite方法，所以如果有些情况不需要进行增强操作可以在supports方法里进行判断。

对返回数据进行真正的操作还是在beforeBodyWrite方法中，我们可以直接在该方法里包装数据，这样就不需要每个接口都进行数据包装了，省去了很多麻烦。

这样尽管我们没有在接口中包装数据，但返回给前端的依然是经过包装后的数据。