专栏名称: 互联网后端架构

主要介绍Java后端架构。其中也会掺杂一些前端、GO、Python、Linux，目标：全栈工程师！---好像很牛叉的样子 ^-^

SpringBoot三招组合拳，手把手教你打出优雅的后端接口

互联网后端架构 · 公众号 · 架构 · 2020-06-29 07:22

正文

前言

一个后端接口大致分为四个部分组成：接口地址（url）、接口请求方式（get、post等）、请求数据（request）、响应数据（response）。如何构建这几个部分每个公司要求都不同，没有什么“一定是最好的”标准，但一个优秀的后端接口和一个糟糕的后端接口对比起来差异还是蛮大的，其中最重要的关键点就是看 是否规范!
本文就一步一步演示如何构建起一个优秀的后端接口体系，体系构建好了自然就有了规范，同时再构建新的后端接口也会十分轻松。

所需依赖包

这里用的是SpringBoot配置项目，本文讲解的重点是后端接口，所以只需要导入一个spring-boot-starter-web包就可以了：

<dependency>   <groupId>org.springframework.bootgroupId>   <artifactId>spring-boot-starter-webartifactId>dependency>

本文还用了swagger来生成API文档，lombok来简化类，不过这两者不是必须的，可用可不用。

参数校验

一个接口一般对参数（请求数据）都会进行安全校验，参数校验的重要性自然不必多说，那么如何对参数进行校验就有讲究了。

业务层校验

首先我们来看一下最常见的做法，就是在业务层进行参数校验：

public String addUser(User user) {     if (user == null || user.getId() == null || user.getAccount() == null || user.getPassword() == null || user.getEmail() == null) {         return "对象或者对象字段不能为空";     }     if (StringUtils.isEmpty(user.getAccount()) || StringUtils.isEmpty(user.getPassword()) || StringUtils.isEmpty(user.getEmail())) {         return "不能输入空字符串";     }     if (user.getAccount().length() < 6 || user.getAccount().length() > 11) {         return "账号长度必须是6-11个字符";     }     if (user.getPassword().length() < 6 || user.getPassword().length() > 16) {         return "密码长度必须是6-16个字符";     }     if (!Pattern.matches("^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$", user.getEmail())) {         return "邮箱格式不正确";     }     // 参数校验完毕后这里就写上业务逻辑     return "success"; }

这样做当然是没有什么错的，而且格式排版整齐也一目了然，不过这样太繁琐了，这还没有进行业务操作呢光是一个参数校验就已经这么多行代码，实在不够优雅。我们来改进一下，使用Spring Validator和Hibernate Validator这两套Validator来进行方便的参数校验！这两套Validator依赖包已经包含在前面所说的web依赖包里了，所以可以直接使用。

Validator + BindResult进行校验

Validator可以非常方便的制定校验规则，并自动帮你完成校验。首先在入参里需要校验的字段加上注解,每个注解对应不同的校验规则，并可制定校验失败后的信息：

@Datapublic class User {    @NotNull(message = "用户id不能为空")    private Long id;
    @NotNull(message = "用户账号不能为空")    @Size(min = 6, max = 11, message = "账号长度必须是6-11个字符")    private String account;
    @NotNull(message = "用户密码不能为空")    @Size(min = 6, max = 11, message = "密码长度必须是6-16个字符")    private String password;
    @NotNull(message = "用户邮箱不能为空")    @Email(message = "邮箱格式不正确")    private String email;}

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

@RestController@RequestMapping("user")public class UserController {    @Autowired    private UserService userService;        @PostMapping("/addUser")    public String addUser(@RequestBody @Valid User user, BindingResult bindingResult) {        // 如果有参数校验失败，会将错误信息封装成对象组装在BindingResult里        for (ObjectError error : bindingResult.getAllErrors()) {            return error.getDefaultMessage();        }        return userService.addUser(user);    }}

这样当请求数据传递到接口的时候Validator就自动完成校验了，校验的结果就会封装到BindingResult中去，如果有错误信息我们就直接返回给前端，业务逻辑代码也根本没有执行下去。此时，业务层里的校验代码就已经不需要了：

public String addUser(User user) {     // 直接编写业务逻辑     return "success"; }

现在可以看一下参数校验效果。我们故意给这个接口传递一个不符合校验规则的参数，先传递一个错误数据给接口，故意将password这个字段不满足校验条件：

{    "account": "12345678",    "email": "[email protected]",    "id": 0,    "password": "123"}

再来看一下接口的响应数据：

image

这样是不是方便很多？不难看出使用Validator校验有如下几个好处：

简化代码，之前业务层那么一大段校验代码都被省略掉了。
使用方便，那么多校验规则可以轻而易举的实现，比如邮箱格式验证，之前自己手写正则表达式要写那么一长串，还容易出错，用Validator直接一个注解搞定。（还有更多校验规则注解，可以自行去了解哦）
减少耦合度，使用Validator能够让业务层只关注业务逻辑，从基本的参数校验逻辑中脱离出来。

使用Validator+ BindingResult已经是非常方便实用的参数校验方式了，在实际开发中也有很多项目就是这么做的，不过这样还是不太方便，因为你每写一个接口都要添加一个BindingResult参数，然后再提取错误信息返回给前端。这样有点麻烦，并且重复代码很多（尽管可以将这个重复代码封装成方法）。我们能否去掉BindingResult这一步呢？当然是可以的！

Validator + 自动抛出异常

我们完全可以将BindingResult这一步给去掉：

@PostMapping("/addUser")public String addUser(@RequestBody @Valid User user) {    return userService.addUser(user);}

去掉之后会发生什么事情呢？直接来试验一下，还是按照之前一样故意传递一个不符合校验规则的参数给接口。
此时我们观察控制台可以发现接口已经引发 MethodArgumentNotValidException 异常了：

image

其实这样就已经达到我们想要的效果了，参数校验不通过自然就不执行接下来的业务逻辑，去掉BindingResult后会自动引发异常，异常发生了自然而然就不会执行业务逻辑。也就是说，我们完全没必要添加相关BindingResult相关操作嘛。不过事情还没有完，异常是引发了，可我们并没有编写返回错误信息的代码呀，那参数校验失败了会响应什么数据给前端呢？
我们来看一下刚才异常发生后接口响应的数据：

没错，是直接将整个错误对象相关信息都响应给前端了！这样就很难受，不过解决这个问题也很简单，就是我们接下来要讲的全局异常处理！

全局异常处理

参数校验失败会自动引发异常，我们当然不可能再去手动捕捉异常进行处理，不然还不如用之前BindingResult方式呢。 又不想手动捕捉这个异常，又要对这个异常进行处理 ，那正好使用SpringBoot全局异常处理来达到一劳永逸的效果！

基本使用

首先，我们需要新建一个类，在这个类上加上 @ControllerAdvice 或 @RestControllerAdvice 注解，这个类就配置成全局处理类了。（这个根据你的Controller层用的是 @Controller 还是 @RestController 来决定）
然后在类中新建方法，在方法上加上 @ExceptionHandler 注解并指定你想处理的异常类型，接着在方法内编写对该异常的操作逻辑，就完成了对该异常的全局处理！
我们现在就来演示一下对参数校验失败抛出的 MethodArgumentNotValidException 全局处理：

@RestControllerAdvicepublic class ExceptionControllerAdvice {
    @ExceptionHandler(MethodArgumentNotValidException.class)    public String MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) {        // 从异常对象中拿到ObjectError对象        ObjectError objectError = e.getBindingResult().getAllErrors().get(0);        // 然后提取错误提示信息进行返回        return objectError.getDefaultMessage();    }    }

我们再来看下这次校验失败后的响应数据：

没错，这次返回的就是我们制定的错误提示信息！我们通过全局异常处理优雅的实现了我们想要的功能！以后我们再想写接口参数校验，就只需要在入参的成员变量上加上Validator校验规则注解，然后在参数上加上 @Valid 注解即可完成校验，校验失败会自动返回错误提示信息，无需任何其他代码！

自定义异常

全局处理当然不会只能处理一种异常，用途也不仅仅是对一个参数校验方式进行优化。在实际开发中，如何对异常处理其实是一个很麻烦的事情。传统处理异常一般有以下烦恼：

是捕获异常( try...catch )还是抛出异常( throws )
是在 controller 层做处理还是在 service 层处理又或是在 dao 层做处理
处理异常的方式是啥也不做，还是返回特定数据，如果返回又返回什么数据
不是所有异常我们都能预先进行捕捉，如果发生了没有捕捉到的异常该怎么办？

以上这些问题都可以用全局异常处理来解决，全局异常处理也叫统一异常处理，全局和统一处理代表什么？ 代表规范！ 规范有了，很多问题就会迎刃而解！
全局异常处理的基本使用方式大家都已经知道了，我们接下来更进一步的规范项目中的异常处理方式：自定义异常。
在很多情况下，我们需要手动抛出异常，比如在业务层当有些条件并不符合业务逻辑，我这时候就可以手动抛出异常从而触发事务回滚。那手动抛出异常最简单的方式就是 throw new RuntimeException("异常信息") 了，不过使用自定义会更好一些：

自定义异常可以携带更多的信息，不像这样只能携带一个字符串。
项目开发中经常是很多人负责不同的模块，使用自定义异常可以统一了对外异常展示的方式。
自定义异常语义更加清晰明了，一看就知道是项目中手动抛出的异常。

我们现在就来开始写一个自定义异常：

@Getter //只要getter方法，无需setterpublic class APIException extends RuntimeException {    private int code;    private String msg;
    public APIException() {        this(1001, "接口错误");    }
    public APIException(String msg) {        this(1001, msg);    }
    public APIException(int code, String msg) {        super(msg);        this.code = code;        this