SpringBoot项目实践之参数校验，统一异常，统一结果

一个Java菜鸟的学习之路 个人博客 youngljx.top

参数校验

数据的校验的重要性就不用说了，即使在前端对数据进行校验的情况下，我们还是要对传入后端的数据再进行一遍校验，避免用户绕过浏览器直接通过一些 HTTP 工具直接向后端请求一些违法数据。

我们最常见的做法，就是在业务层进行参数校验，不过这样太繁琐了，使用Spring Validator和Hibernate Validator这两套Validator来进行方便的参数校验！这两套Validator依赖包已经包含在前面所说的web依赖包里了，所以可以直接使用。

1. 一些常用的字段验证的注解

• @NotEmpty 被注释的字符串的不能为 null 也不能为空
• @NotBlank 被注释的字符串非 null，并且必须包含一个非空白字符
• @Null 被注释的元素必须为 null
• @NotNull 被注释的元素必须不为 null
• @AssertTrue 被注释的元素必须为 true
• @AssertFalse 被注释的元素必须为 false
• @Pattern(regex=,flag=)被注释的元素必须符合指定的正则表达式
• @Email 被注释的元素必须是 Email 格式。
• @Min(value)被注释的元素必须是一个数字，其值必须大于等于指定的最小值
• @Max(value)被注释的元素必须是一个数字，其值必须小于等于指定的最大值
• @DecimalMin(value)被注释的元素必须是一个数字，其值必须大于等于指定的最小值
• @DecimalMax(value) 被注释的元素必须是一个数字，其值必须小于等于指定的最大值
• @Size(max=, min=)被注释的元素的大小必须在指定的范围内
• @Digits (integer, fraction)被注释的元素必须是一个数字，其值必须在可接受的范围内
• @Past被注释的元素必须是一个过去的日期
• @Future 被注释的元素必须是一个将来的日期
• …

2.Validator + BindResult进行校验

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

@Data
public 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;
}

验证请求体(RequestBody)

校验规则和错误提示信息配置完毕后，接下来只需要在接口需要校验的参数上加上 @Valid注解，如果验证失败，它将抛出MethodArgumentNotValidException，继续添加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中去，如果有错误信息我们就直接返回给前端，业务逻辑代码也根本没有执行下去。

验证请求参数(Path Variables 和 Request Parameters)

一定一定不要忘记在类上加上 Validated 注解了，这个参数可以告诉 Spring 去校验方法参数。

@RestController
@RequestMapping("/api")
@Validated
public class PersonController {

    @GetMapping("/person/{id}")
    public ResponseEntity<Integer> getPersonByID(@Valid @PathVariable("id") @Max(value = 5,message = "超过 id 的范围了") Integer id) {
        return ResponseEntity.ok().body(id);
    }
}

统一异常处理

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

异常处理流程：

1.自定义全局异常类，使用@ControllerAdvice，控制器增强

2.自定义错误代码及错误信息，两种异常最终会采用统一的信息格式来表示，错误代码+错误信息。

3.对于可预知的异常由程序员在代码中主动抛出，由SpringMVC统一捕获。

4.不可预知异常通常是由于系统出现bug、或一些外界因素（如网络波动、服务器宕机等），异常类型为RuntimeException类型（运行时异常）。

我们通常使用 @ControllerAdvice 和 @ExceptionHandler 处理全局异常

相关注解：

1. @ControllerAdvice :注解定义全局异常处理类
2. @ExceptionHandler :注解声明异常处理方法

自定义异常类型

在很多情况下，我们需要手动抛出异常，比如在业务层当有些条件并不符合业务逻辑，我这时候就可以手动抛出异常从而触发事务回滚。一般我们处理的都是 RuntimeException ，所以如果你需要自定义异常类型的话直接集成这个类就可以了，例如：

public class ResourceNotFoundException extends RuntimeException {
    private String message;

    public ResourceNotFoundException() {
        super();
    }

    public ResourceNotFoundException(String message) {
        super(message);
        this.message = message;
    }

    @Override
    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

新建异常处理类处理全局异常

@ControllerAdvice(assignableTypes = {ExceptionController.class})//可以通过 assignableTypes指定特定的 Controller 类，让异常处理类只处理特定类抛出的异常
@ResponseBody
public class GlobalExceptionHandler {

    ErrorResponse illegalArgumentResponse = new ErrorResponse(new IllegalArgumentException("参数错误!"));
    ErrorResponse resourseNotFoundResponse = new ErrorResponse(new ResourceNotFoundException("Sorry, the resourse not found!"));

    @ExceptionHandler(value = Exception.class)// 拦截所有异常, 这里只是为了演示，一般情况下一个方法特定处理一种异常
    public ResponseEntity<ErrorResponse> exceptionHandler(Exception e) {

        if (e instanceof IllegalArgumentException) {
            return ResponseEntity.status(400).body(illegalArgumentResponse);
        } else if (e instanceof ResourceNotFoundException) {
            return ResponseEntity.status(404).body(resourseNotFoundResponse);
        }
        return null;
    }
}

统一结果响应

目前的前后端开发大部分数据的传输格式都是json，因此定义一个统一规范的数据格式有利于前后端的交互与UI的展示。

结果类枚举

@Getter
public enum ResultCodeEnum {
    SUCCESS(true,20000,"成功"),
    UNKNOWN_ERROR(false,20001,"未知错误"),,
    PARAM_ERROR(false,20002,"参数错误"),
    ;

    // 响应是否成功
    private Boolean success;
    // 响应状态码
    private Integer code;
    // 响应信息
    private String message;

    ResultCodeEnum(boolean success, Integer code, String message) {
        this.success = success;
        this.code = code;
        this.message = message;
    }
}

统一结果类

1.外界只可以调用统一返回类的方法，不可以直接创建，因此构造器私有；

2.内置静态方法，返回对象；

3.为便于自定义统一结果的信息，建议使用链式编程，将返回对象设类本身，即return this;

4.响应数据由于为json格式，可定义为JsonObject或Map形式；

@Data
public class R {
    private Boolean success;

    private Integer code;

    private String message;

    private Map<String, Object> data = new HashMap<>();

    // 构造器私有
    private R(){}

    // 通用返回成功
    public static R ok() {
        R r = new R();
        r.setSuccess(ResultCodeEnum.SUCCESS.getSuccess());
        r.setCode(ResultCodeEnum.SUCCESS.getCode());
        r.setMessage(ResultCodeEnum.SUCCESS.getMessage());
        return r;
    }

    // 通用返回失败，未知错误
    public static R error() {
        R r = new R();
        r.setSuccess(ResultCodeEnum.UNKNOWN_ERROR.getSuccess());
        r.setCode(ResultCodeEnum.UNKNOWN_ERROR.getCode());
        r.setMessage(ResultCodeEnum.UNKNOWN_ERROR.getMessage());
        return r;
    }

    // 设置结果，形参为结果枚举
    public static R setResult(ResultCodeEnum result) {
        R r = new R();
        r.setSuccess(result.getSuccess());
        r.setCode(result.getCode());
        r.setMessage(result.getMessage());
        return r;
    }

    /**------------使用链式编程，返回类本身-----------**/

    // 自定义返回数据
    public R data(Map<String,Object> map) {
        this.setData(map);
        return this;
    }

    // 通用设置data
    public R data(String key,Object value) {
        this.data.put(key, value);
        return this;
    }

    // 自定义状态信息
    public R message(String message) {
        this.setMessage(message);
        return this;
    }

    // 自定义状态码
    public R code(Integer code) {
        this.setCode(code);
        return this;
    }

    // 自定义返回结果
    public R success(Boolean success) {
        this.setSuccess(success);
        return this;
    }
}

控制层返回

@RestController
@RequestMapping("/api/v1/users")
public class TeacherAdminController {

    @Autowired
    private UserService userService;

    @GetMapping
    public R list() {
        List<Teacher> list = teacherService.list(null);
        return R.ok().data("itms", list).message("用户列表");
    }
} 

仅此简单总结记录一下，未完待续

参考文章：

项目实践：Spring Boot 三招组合拳，手把手教你打出优雅的后端接口

项目经理说：统一结果，统一异常，统一日志

SpringBoot 处理异常的几种常见姿势