通过需求文档，描述清楚业务流程，定义好相关的设计规范。根据项目大小划分好前台和后台的功能需求，通过需求来得到对应的模块。

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

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

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

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

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

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

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

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

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

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

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

主要是对RESTful接口设计做一个介绍。

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

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

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

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

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

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-iPfV1rRu-1662523338889)(C:\Users\Hasee\AppData\Roaming\Typora\typora-user-images\image-20220906214352990.png)]

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

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

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-V9VfIYYH-1662523338892)(C:\Users\Hasee\AppData\Roaming\Typora\typora-user-images\image-20220906215237691.png)]

具体可以参考这篇文章：HTTP状态码有哪些分类？

同样我们可以这么设计：

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-AMuiZ7de-1662523338893)(C:\Users\Hasee\AppData\Roaming\Typora\typora-user-images\image-20220906215907754.png)]

这样设计的好处是可以把错误类型归类到某个区间内，如果区间不够，可以设计成4位数。 这样前端开发人员在得到返回值后，根据状态码就可以知道，大概什么错误，再根据msg相关的信息描述，可以快速定位。

这个字段相对理解比较简单，就是发生错误时，如何友好的进行提示。一般的设计是和code状态码一起设计。

返回数据体，json格式，根据不同的业务又不同的json体。一般来说返回给前端时会结合msg、code一起返回。

我们先来看一段数据校验的代码：

是不是感觉比较熟悉，在最开始不熟悉开发的时候，都会这么写过。虽然我们阅读这段代码对参数的校验是没有问题的，而且排版也还看得过去。但是每个接口都这么写显然会看的比较繁琐。而且还没到业务处理，参数校验的代码就这么多了，显然会让人头大。

在我们引入的依赖 spring-boot-starter-web 中包含了 Validator ，它可以非常方便的定制校验规则，并自动完成校验。只需要在需要校验的字段加上对应的注解即可，message后面填校验失败后的信息。

校验规则和错误提示信息配置完毕后，接下来只需要在接口中需要校验的参数上加上@Valid 注解，并添加BindResult参数即可方便完成验证。

BindResult作用：如果有参数校验失败，会将错误信息封装成对象组装在BindingResult里

当然，每个接口中都添加BindResult显然会比较繁琐，我们完全可以把BindResult去掉

例如：

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

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

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

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

例如：

我们在 1.0.1小节 中了解了返回格式的写法，我们自定义异常也可以参考这一小节来编写。

当然，我们也需要在全局异常类中添加上我们对自定义异常的处理。

这样就对异常的处理就比较规范了，当然还可以添加对Exception的处理，这样无论发生什么异常我们都能屏蔽掉然后响应数据给前端，不过建议最后项目上线时这样做，能够屏蔽掉错误信息暴露给前端，在开发中为了方便调试还是不要这样做。

在上一大节中，我们对全局异常处理和自定义异常已经处理完毕，但是当我们抛出自定义异常的时候，全局异常处理只响应了异常中的错误信息msg给前端，并没有将错误代码code返回。这里就要说到数据统一响应了。

我们尽管对参数校验方式和异常处理方式做好了规范，但是对响应数据没有做好规范。

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

可以参考我们自定义异常类，也来一个响应信息代码code和响应信息说明msg。

然后我们修改全局异常处理的返回值：

通过上面的操作，我们将状态码和响应说明还有错误提示数据都返给了前端，并且是所有异常都会返回相同的格式。

这样无论是正确响应还是发生异常，响应数据的格式都是统一的。

数据格式规范好了，不过响应码code和响应信息msg还没有规范。所以，必须要将响应码和响应信息给规范起来。

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

我们还要把状态码和信息就会一一对应，这样比较好维护。

这里要修改响应体的构造方法，让其只准接受响应码枚举来设置响应码和响应信息。

同时我们还应当对全局异常处理的响应码设置方式进行修改：

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

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

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

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

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

在上一节中，我们得到了一个统一响应体ResultVo，里面具有code、msg、data。

如果返回给前端的数据，要求给出分页信息，那么ResponsePages类中，还需要有Page类，其中至少包括当前页数，每页显示条数和总条数信息。分页使用github的pagehelper工具类来完成。

很多时候我们往往需要多种返回数据，例如添加返回分页信息，我们可以灵活的根据业务需求修改ResultVo，但是切记不要在项目进行到中段时再反复修改，一定要在项目开始时就确立，这就是接口开发文档存在的意义。

参考面向对象原则，接口设计也有六大原则，分别是单一职责原则、里氏替换原则、依赖倒置原则、接口隔离原则、迪米特法则、开闭原则。

接下来介绍一些其他的设计原则。

常规性校验：包括必填字段，长度检测。格式校验等。

鉴权校验：当前请求必须符合权限等。

业务校验：根据实际业务而定，比如订单金额不能小于0等等。

作用：在接口层做用户鉴权校验和参数校验，比如做ID基础校验，id"id":"20201219", "name":"21.59"， "age":"ftp_1002" ... }, ] 复制代码 请求参数说明 字段名字段说明字段类型是否必填字段1说明字段1的作用varchar(50)是字段2说明字段2的作用int是字段3说明字段3的作用decimal是 响应示例

成功响应编码：

失败响应编码：

由于不同的公司有不同的文档格式要求，此处只列举一个仅供参考的案例。

封面还是比较重要的，毕竟是打开文档的第一眼内容，下面用阿里的文档作为参考，可以看到封面一般是如下内容：

文档信息主要记录这份文件的产生日期以及具体的创建打印日期等。

版权声明：（现在这个时代版权是极其重要的）

xxxx所有，不得三方借阅、出让、出版

版本历史是很重要的，每次改动都需要有详细的记录，这样才能保证文档的干净和有效，同时可以方便review的时候，对于文档的修订者进行文档审查。

好的文档一定有好的目录，只要按照一定的规范和格式写出来的文档，一般看上去都是十分舒服的。还是用阿里的开发手册做参考

这一部分发挥的自由空间就比较大了，不同的业务不同的公司不同的需求不同的人都能写出万千种格式的文档，所以这里也是给一个样例做参考使用。是否有实用价值因人而异。

为了不让整个目录树太长，这里没有做标题说明=-=

需要解决什么问题，为什么要这份文档，这份文档有什么参考价值？

接口方可以提供什么内容，接口方需要对接方的那些内容，以及提供的其他信息，比如需要对接方提供 系统应用id，系统唯一标识。向对接方提供密钥等等

​ 1. 测试联调：分配测试的密钥，测试环境的账户和密码以及其他信息

​ 2. 上线：上线之后需要做什么事情，如：替换生产url，替换生产环境账户密码，替换密钥为生产密钥等等

可以是本次对接使用的算法，通信协议，可以是术语说明或者和业务相关的其他说明，以及对接的要求都可以，发挥空间很大，自由设计。

报文规范是接口对接的核心部分，因为对接大部分的时间基本都是花在接口参数调试和请求调试等。所以报文规范算是非常重要的内容。具体内容可以参考简单版本的接口描述，也可以使用目录格式进行对应的描述

也是比较重要的部分，也是比较花时间的地方，需要大量调试来打通接口的地方，存在以下的几个要点。

加解密规范参考：

一般的加密方式，一般情况下做到下面这种形式基本可以屏蔽大部分的攻击：

这里基本可以照抄简单接口模板，因为接口描述每个人的描述不同，下面给出一些基本上涉及的点，另外，到了这一步就尽量用案例辅助，因为案例可以帮助接口阅读者更快速的上手和理解，注意这一部分的内容：实用性大于理论性。

具体接口：

可能这部分和说明书一样基本没人看，所以不做过多的解释，附录不必写的很详细的，这里可以随意施展。

1.CSDN_如何设计和编写标准的后端接口 2.开源博客_API 接口规范 3.CSDN_什么是接口文档，如何写接口，有什么规范？