SpringBoot统一接口返回和全局异常

目录

1、写在最前

2、接口请求

2.1、参数校验

2.1.1、业务层校验

2.1.2、Validator + BindResult进行校验

2.1.3、注解说明

2.1.4、实战演练 

2.1.3、Validator + 自动抛出异常

3、业务逻辑：异常处理

3.1全局异常处理

3.1.1、基本使用

3.2、自定义异常

4、数据统一响应

4.1、SpringBoot默认返回格式

4.1.1、字符串

4.1.2、实体类

4.2、参数说明

4.2.1、返回格式

4.2.2、CODE状态码 

4.2.3、状态码

4.2.4、数据

5、进阶用法

5.1 类介绍

5.2 全局统一返回

5.3、全局自定义统一响应体

5.4、响应码枚举

5.5、全局异常处理器

5.6、统一返回结果处理类最终版

6、总结

---

1、写在最前

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

        后端接口大致分为四个部分组成：接口地址（url）、接口请求方式（get、post等）、请求数据（request）、响应数据（response）。如何构建，这是我们应该深入思考的问题，公司不同，规范不同，要求不同。不管公司有没有要求，我们对自己必须要有要求。

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

今天的这篇文章我们主要介绍，怎么统一处理下接口的返回格式问题。

简单更新接口逻辑，其中包括：

① 请求参数、响应结果日志打印

② 基础参数的校验

③更新用户业务主逻辑

④ 全局异常的捕获

⑤ 对Result结果的封装。这其中貌似一个步骤也不能省略，但却导致我们写代码效率低下，其实最重要的一步仅仅是③

那么我们改如何改进呢？

① 请求参数、响应结果日志打印 -> 使用在controller方法外对做切面统一打印日志（非GET方法都会打印）
② 基础参数的校验 -> 使用hibernate validate做操作校验
④ 全局异常的捕获 -> 使用@ControllerAdvice写全局异常处理类控制异常展现方式
⑤ 对Result结果的封装 -> 实现ResponseBodyAdvice接口，对接口响应体统一处理

请求：请求方式，请求数据格式，参数检验

逻辑处理：日志记录。。。。。。

返回：统一返回对象，包装，异常处理

2、接口请求

2.1、参数校验

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

2.1.1、业务层校验

来看一下最常见的做法，业务层进行参数校验： 

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 "邮箱格式不正确";
     }

2.1.2、Validator + BindResult进行校验

为什么要用validator？

javax.validation的一系列注解可以帮我们完成参数校验,免去繁琐的串行校验 

什么是javax.validation 

JSR303 是一套JavaBean参数校验的标准，它定义了很多常用的校验注解，

2.1.3、注解说明

• @NotNull：不能为null，但可以为empty(""," "," ")

• @NotEmpty：不能为null，而且长度必须大于0 (" "," ")

• @NotBlank：只能作用在String上，不能为null，而且调用trim()后，长度必须大于0("test") 即：必须有实际字符

  

2.1.4、实战演练 

        使用Spring Validator，Validator依赖包在SpringBoot中已经包含在starter-web中，可直接使用，2.3以后需要自己引入。

    org.springframework.boot
    spring-boot-starter-validation
    2.3.10.RELEASE

        1.对参数的字段进行注解标注

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

import lombok.Data;
import org.hibernate.validator.constraints.Length;
import javax.validation.constraints.Email;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;

@Data
public class User {
    @NotNull(message = "用户id不能为空")
    private Long id;

    /** 用户名*/
    @NotBlank(message = "用户名不能为空")
    @Length(max = 20, message = "用户名不能超过{max}个字符")
    @Pattern(regexp = "^[\\u4E00-\\u9FA5A-Za-z0-9\\*]*$", message = "用户昵称限制：最多20字符，包含文字、字母和数字")
    private String username;

    @NotNull(message = "用户密码不能为空")
    @Size(min = 6, max = 11, message = "密码长度必须是6-16个字符")
    private String password;

    @NotNull(message = "用户邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;

    /** 手机号*/
    @NotBlank(message = "手机号不能为空")
    @Pattern(regexp = "^[1][3,4,5,6,7,8,9][0-9]{9}$", message = "手机号格式有误")
    private String mobile;
}

      2.  @Validated 声明要检查的参数

        校验规则和错误提示信息配置完毕后，接下来只需要在接口需要校验的参数上加上@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中去，如果有错误信息我们就直接返回给前端，业务逻辑代码也根本没有执行下去。此时，业务层里的校验代码就已经不需要了：

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

{
    "uaername": "testusername",
    "email": "[email protected]",
    "id": 0,
    "password": ,
    "mobile":"13372677829"
}

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

不难看出使用Validator校验有如下几个好处：

• 代码简化：之前业务层那么一大段校验代码都被省略掉了。
• 使用方便：那么多校验规则可以轻而易举的实现，比如邮箱格式验证，手机号码校验等，用Validator直接一个注解搞定。
• 减少耦合度：使用Validator能够让业务层只关注业务逻辑，从基本的参数校验逻辑中脱离出来。

        使用Validator+ BindingResult已经是非常方便实用的参数校验方式了，在实际开发中也有很多项目就是这么做的，不过这样还是不太方便，因为你每写一个接口都要添加一个Result参数，然后再提取错误信息返回给前端。

这样有点麻烦，并且重复代码很多（尽管可以将这个重复代码封装成方法）。我们能否去掉BindingResult这一步呢？当然是可以的！

2.1.3、Validator + 自动抛出异常

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

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

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

        去掉BindingResult后会自动引发异常，异常发生了自然而然就不会执行业务逻辑。也就是说，我们完全没必要添加相关BindingResult相关操作嘛。

3、业务逻辑：异常处理

3.1全局异常处理

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

为了优雅一点,我们将参数异常,业务异常,统一做了一个全局异常,将控制层的异常包装到我们自定义的异常中

为了优雅一点,我们还做了一个统一的结构体,将请求的code,和msg,data一起统一封装到结构体中,增加了代码的复用性

3.1.1、基本使用

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

@RestControllerAdvice = @ControllerAdvice + @ResponseBody + ..

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

我们现在就来演示一下对参数校验失败抛出的MethodArgumentNotValidException全局处理：

@RestControllerAdvice
public class ExceptionControllerAdvice {

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

}

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

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

3.2、自定义异常

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

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

以上这些问题都可以用全局异常处理来解决，全局异常处理也叫统一异常处理，全局和统一处理代表什么？代表规范！规范有了，很多问题就会迎刃而解！

全局异常处理的基本使用方式大家都已经知道了，我们接下来更进一步的规范项目中的异常处理方式：自定义异常

在很多情况下，我们需要手动抛出异常，比如在业务层当有些条件并不符合业务逻辑，我这时候就可以手动抛出异常从而触发事务回滚。那手动抛出异常最简单的方式就是throw new RuntimeException("异常信息")了，不过使用自定义会更好一些：

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

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

@Getter //只要getter方法，无需setter
public 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.msg = msg;
    }
}

在刚才的全局异常处理类中记得添加对我们自定义异常的处理：

@ExceptionHandler(APIException.class)
public String APIExceptionHandler(APIException e) {
    return e.getMsg();
}

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

现在全局异常处理和自定义异常已经弄好了，不知道大家有没有发现一个问题，就是当我们抛出自定义异常的时候全局异常处理只响应了异常中的错误信息msg给前端，并没有将错误代码code返回。这就要引申出我们接下来要讲的东西了：数据统一响应

4、数据统一响应

        现在我们规范好了参数校验方式和异常处理方式，然而还没有规范响应数据！比如我要获取一个分页信息数据，获取成功了呢自然就返回的数据列表，获取失败了后台就会响应异常信息，即一个字符串，就是说前端开发者压根就不知道后端响应过来的数据会是啥样的！所以，统一响应数据是前后端规范中必须要做的！

4.1、SpringBoot默认返回格式

4.1.1、字符串

@GetMapping("/getUserName")
public String getUserName(){
    return "HuaGe";
}

调用接口返回结果：

HuaGe

4.1.2、实体类

@GetMapping("/getUserName")
public User getUserName(){
    return new User("HuaGe",18,"男");
}

调用接口返回结果：

{
  "name": "HuaGe",
  "age": "18",
  "性别": "男", 
}

4.2、参数说明

4.2.1、返回格式

最初返回给前端我们一般用JSON体方式，定义如下：

{
  #返回状态码：后台可以维护一套统一的状态码；后台可以维护一套统一的状态码；
  code:integer,
  #返回信息描述，接口调用成功/失败的提示信息
  message:string,
  #返回值
  data:object
}

4.2.2、CODE状态码 

code返回状态码，开发的时候需要什么，就添加什么。

可以参考HTTP请求返回的状态码

常见的HTTP状态码：

200 - 请求成功

301 - 资源（网页等）被永久转移到其它URL

404 - 请求的资源（网页等）不存在

500 - 内部服务器错误

可以参考这样的设计，这样的好处就把错误类型归类到某个区间内，如果区间不够，可以设计成4个数字 

#1000～1999 区间表示参数错误

#2000～2999 区间表示用户错误

#3000～3999 区间表示接口异常

4.2.3、状态码

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

/**
 * 全局异常处理枚举类
 */
public enum ResultEnum {

    BODY_NOT_MATCH(400,"请求的数据格式不符!"),
    SIGNATURE_NOT_MATCH(401,"请求的数字签名不匹配!"),
    NOT_FOUND(404, "未找到该资源!"),
    INTERNAL_SERVER_ERROR(500, "服务器内部错误!"),
    SERVER_BUSY(503,"服务器正忙，请稍后再试!"),
    /** 成功 */
    SUCCESS(1000, "成功"),
    /** 无法找到资源错误 */
    NOT_FOUNT_RESOURCE(1001,"没有找到相关资源!"),
    /** 请求参数有误 */
    PARAMETER_ERROR(1002,"请求参数有误!"),
    /** 确少必要请求参数异常 */
    PARAMETER_MISSING_ERROR(1003,"确少必要请求参数!"),
    /** 确少必要请求参数异常 */
    REQUEST_MISSING_BODY_ERROR(1004,"缺少请求体!"),

    /** 未知错误 */
    SYSTEM_ERROR(9998,"未知的错误!"),
    /** 系统错误 */
    UNKNOWN_ERROR(9999,"未知的错误!");

    private Integer code;
    private String message;

    ResultEnum(Integer code, String message) {
        this.code = code;
        this.message = message;
    }

    public Integer getCode() {
        return code;
    }
    public String getMessage() {
        return message;
    }

}

状态码和信息就会一一对应，比较好维护。

4.2.4、数据

返回数据体，JSON格式，根据不同的业务又不同的JSON体。

@Data
public class Result {
    
    private int code;
    
    private String message;
    
    private T data;

    public Result() {}
    public Result(int code, String message) {
        this.code = code;
        this.message = message;
    }
    
    /**
     * 成功
     */
    public static  Result success(T data) {
        Result result = new Result();
        result.setCode(ResultEnum.SUCCESS.getCode());
        result.setMessage(ResultEnum.SUCCESS.getMessage());
        result.setData(data);
        return result;
    }

    /**
     * 失败
     */
    public static  Result error(int code, String message) {
        return new Result(code, message);
    }
}

上面两步定义了数据返回格式和状态码，接下来就要看下在接口中如何使用了。

@RestController
@RequestMapping("/users")
public class UserController {

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public ResultaddUser(@Validated @RequestBody User user) {
        user.setId(10000L);
        user.setCreateTime(new Date());
        return Result.success(user);
    }

}

 返回

{
    "code": 0,
    "message": "成功",
    "data": "huage"
}

Result.success()这段逻辑显然很多余，每个方法都要这样写一遍 

5、进阶用法

5.1 类介绍

@ResponseBodyAdvice： 该接口是SpringMVC 4.1提供的，它允许在执行@ResponseBody后自定义返回数据，用来封装统一数据格式返回；

@RestControllerAdvice： 该注解是对Controller进行增强的，可以全局捕获抛出的异常。

5.2 全局统一返回

• 新建ResponseAdvice类；
• 实现ResponseBodyAdvice接口，实现supports、beforeBodyWrite方法；
• 该类用于统一封装controller中接口的返回结果。

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

/**
 * 全局统一返回
 */
//加上需要扫描的包
@ControllerAdvice(basePackages = "com.ykx.code.controller")
public class GlobResponseBodyAdvice implements  ResponseBodyAdvice