SpringBoot写出优雅的后端接口

忘是亡心i 2023-07-24 03:08 44阅读 0赞

### SpringBoot写出优雅的后端接口 ###

*   *   *   *  pom.xml
             *  业务层校验
             *  Validator + BindResult进行校验
             *  Validator + 自动抛出异常
             *  全局异常处理
             *  自定义异常
             *  数据统一响应-自定义统一响应体
             *  响应码枚举
             *  全局处理响应数据

#### pom.xml ####

<parent>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>2.0.0.RELEASE</version>
        </parent>
    
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
        </dependencies>

#### 业务层校验 ####

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进行校验 ####

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;
    }

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

{ 
        "account": "12345678",
        "email": "123@qq.com",
        "id": 0,
        "password": "123"
    }

![在这里插入图片描述][2020040910532825.png]

> 这样是不是方便很多？不难看出使用Validator校验有如下几个好处：  
> 简化代码，之前业务层那么一大段校验代码都被省略掉了。  
> 使用方便，那么多校验规则可以轻而易举的实现，比如邮箱格式验证，之前自己手写正则表达式要写那么一长串，还容易出错，用Validator直接一个注解搞定。（还有更多校验规则注解，可以自行去了解哦）  
> 减少耦合度，使用Validator能够让业务层只关注业务逻辑，从基本的参数校验逻辑中脱离出来。  
> 使用Validator+ BindingResult已经是非常方便实用的参数校验方式了，在实际开发中也有很多项目就是这么做的，不过这样还是不太方便，因为你每写一个接口都要添加一个BindingResult参数，然后再提取错误信息返回给前端。  
> 这样有点麻烦，并且重复代码很多（尽管可以将这个重复代码封装成方法）。我们能否去掉BindingResult这一步呢？当然是可以的！

#### Validator + 自动抛出异常 ####

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

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

> 去掉之后会发生什么事情呢？直接来试验一下，还是按照之前一样故意传递一个不符合校验规则的参数给接口。此时我们观察控制台可以发现接口已经引发MethodArgumentNotValidException异常了：  
> ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70]  
> 没错，是直接将整个错误对象相关信息都响应给前端了！这样就很难受，不过解决这个问题也很简单，就是我们接下来要讲的全局异常处理！

#### 全局异常处理 ####

> 基本使用  
> 首先，我们需要新建一个类，在这个类上加上@ControllerAdvice或@RestControllerAdvice注解，这个类就配置成全局处理类了。（这个根据你的Controller层用的是@Controller还是@RestController来决定）  
> 然后在类中新建方法，在方法上加上@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();
        }
    
    }

![在这里插入图片描述][20200409105629474.png]

#### 自定义异常 ####

> 全局处理当然不会只能处理一种异常，用途也不仅仅是对一个参数校验方式进行优化。在实际开发中，如何对异常处理其实是一个很麻烦的事情。传统处理异常一般有以下烦恼：  
> 是捕获异常(try…catch)还是抛出异常(throws)  
> 是在controller层做处理还是在service层处理又或是在dao层做处理  
> 处理异常的方式是啥也不做，还是返回特定数据，如果返回又返回什么数据  
> 不是所有异常我们都能预先进行捕捉，如果发生了没有捕捉到的异常该怎么办？  
> 以上这些问题都可以用全局异常处理来解决，全局异常处理也叫统一异常处理，全局和统一处理代表什么？代表规范！规范有了，很多问题就会迎刃而解！  
> 全局异常处理的基本使用方式大家都已经知道了，我们接下来更进一步的规范项目中的异常处理方式：自定义异常。  
> 在很多情况下，我们需要手动抛出异常，比如在业务层当有些条件并不符合业务逻辑，我这时候就可以手动抛出异常从而触发事务回滚。那手动抛出异常最简单的方式就是throw new RuntimeException(“异常信息”)了，不过使用自定义会更好一些：  
> 自定义异常可以携带更多的信息，不像这样只能携带一个字符串。  
> 项目开发中经常是很多人负责不同的模块，使用自定义异常可以统一了对外异常展示的方式。  
> 自定义异常语义更加清晰明了，一看就知道是项目中手动抛出的异常。  
> 我们现在就来开始写一个自定义异常：

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返回。这就要引申出我们接下来要讲的东西了：数据统一响应

#### 数据统一响应-自定义统一响应体 ####

public class ResultVO<T> { 
        /** * 状态码，比如1000代表响应成功 */
        private int code;
        /** * 响应信息，用来说明响应情况 */
        private String msg;
        /** * 响应的具体数据 */
        private T data;
    
        public ResultVO(T data) { 
            this(1000, "success", data);
        }
    
        public ResultVO(int code, String msg, T data) { 
            this.code = code;
            this.msg = msg;
            this.data = data;
        }
    }

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

@ExceptionHandler(APIException.class)
    public ResultVO<String> APIExceptionHandler(APIException e) { 
        // 注意哦，这里返回类型是自定义响应体
        return new ResultVO<>(e.getCode(), "响应失败", e.getMsg());
    }
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResultVO<String> MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) { 
        ObjectError objectError = e.getBindingResult().getAllErrors().get(0);
        // 注意哦，这里返回类型是自定义响应体
        return new ResultVO<>(1001, "参数校验失败", objectError.getDefaultMessage());
    }

> 我们再来看一下此时如果发生异常了会响应什么数据给前端：  
> ![在这里插入图片描述][20200409105948938.png]  
> OK，这个异常信息响应就非常好了，状态码和响应说明还有错误提示数据都返给了前端，并且是所有异常都会返回相同的格式！异常这里搞定了，别忘了我们到接口那也要修改返回类型，我们新增一个接口好来看看效果：

@GetMapping("/getUser")
    public ResultVO<User> getUser() { 
        User user = new User();
        user.setId(1L);
        user.setAccount("12345678");
        user.setPassword("12345678");
        user.setEmail("123@qq.com");
    
        return new ResultVO<>(user);
    }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 1]

> 这样无论是正确响应还是发生异常，响应数据的格式都是统一的，十分规范！  
> 数据格式是规范了，不过响应码code和响应信息msg还没有规范呀！大家发现没有，无论是正确响应，还是异常响应，响应码和响应信息是想怎么设置就怎么设置，要是10个开发人员对同一个类型的响应写10个不同的响应码，那这个统一响应体的格式规范就毫无意义！所以，必须要将响应码和响应信息给规范起来。

#### 响应码枚举 ####

public enum ResultCode { 
    
        SUCCESS(1000, "操作成功"),
    
        FAILED(1001, "响应失败"),
    
        VALIDATE_FAILED(1002, "参数校验失败"),
    
        ERROR(5000, "未知错误");
    
        private int code;
        private String msg;
    
        ResultCode(int code, String msg) { 
            this.code = code;
            this.msg = msg;
        }
    
    }

> 然后修改响应体的构造方法，让其只准接受响应码枚举来设置响应码和响应信息：

public ResultVO(T data) { 
        this(ResultCode.SUCCESS, data);
    }
    
    public ResultVO(ResultCode resultCode, T data) { 
        this.code = resultCode.getCode();
        this.msg = resultCode.getMsg();
        this.data = data;
    }

> 然后同时修改全局异常处理的响应码设置方式：

@ExceptionHandler(APIException.class)
    public ResultVO<String> APIExceptionHandler(APIException e) { 
        // 注意哦，这里传递的响应码枚举
        return new ResultVO<>(ResultCode.FAILED, e.getMsg());
    }
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResultVO<String> MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) { 
        ObjectError objectError = e.getBindingResult().getAllErrors().get(0);
        // 注意哦，这里传递的响应码枚举
        return new ResultVO<>(ResultCode.VALIDATE_FAILED, objectError.getDefaultMessage());
    }

#### 全局处理响应数据 ####

> 接口返回统一响应体 + 异常也返回统一响应体，其实这样已经很好了，但还是有可以优化的地方。要知道一个项目下来定义的接口搞个几百个太正常不过了，要是每一个接口返回数据时都要用响应体来包装一下好像有点麻烦，有没有办法省去这个包装过程呢？当然是有滴，还是要用到全局处理。  
> 首先，先创建一个类加上注解使其成为全局处理类。然后继承ResponseBodyAdvice接口重写其中的方法，即可对我们的controller进行增强操作，具体看代码和注释：

@RestControllerAdvice(basePackages = { "com.controller"}) // 注意哦，这里要加上需要扫描的包
    public class ResponseControllerAdvice implements ResponseBodyAdvice<Object> { 
        @Override
        public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> aClass) { 
            // 如果接口返回的类型本身就是ResultVO那就没有必要进行额外的操作，返回false
            return !returnType.getGenericParameterType().equals(ResultVO.class);
        }
    
        @Override
        public Object beforeBodyWrite(Object data, MethodParameter returnType, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest request, ServerHttpResponse response) { 
            // String类型不能直接包装，所以要进行些特别的处理
            if (returnType.getGenericParameterType().equals(String.class)) { 
                ObjectMapper objectMapper = new ObjectMapper();
                try { 
                    // 将数据包装在ResultVO里后，再转换为json字符串响应给前端
                    return objectMapper.writeValueAsString(new ResultVO<>(data));
                } catch (JsonProcessingException e) { 
                    throw new APIException("返回String类型错误");
                }
            }
            // 将原本的数据包装在ResultVO里
            return new ResultVO<>(data);
        }
    }

> 重写的这两个方法是用来在controller将数据进行返回前进行增强操作，supports方法要返回为true才会执行beforeBodyWrite方法，所以如果有些情况不需要进行增强操作可以在supports方法里进行判断。对返回数据进行真正的操作还是在beforeBodyWrite方法中，我们可以直接在该方法里包装数据，这样就不需要每个接口都进行数据包装了，省去了很多麻烦。  
> 我们可以现在去掉接口的数据包装来看下效果：

@GetMapping("/getUser")
    public User getUser() { 
        User user = new User();
        user.setId(1L);
        user.setAccount("12345678");
        user.setPassword("12345678");
        user.setEmail("123@qq.com");
        // 注意哦，这里是直接返回的User类型，并没有用ResultVO进行包装
        return user;
    }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 2]

> 注意：beforeBodyWrite方法里包装数据无法对String类型的数据直接进行强转，所以要进行特殊处理，这里不讲过多的细节，有兴趣可以自行深入了解。  
> 下期再见。。。

[2020040910532825.png]: /images/20230528/e6ee3f0a9fb84ab98286d1781213fefc.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70]: /images/20230528/12532a5038b24bdca021d9512a51992f.png
[20200409105629474.png]: /images/20230528/bd48a213404845caabf462932d96c41f.png
[20200409105948938.png]: /images/20230528/c5a08a1a6bc04eb697a2cbe79de72639.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 1]: /images/20230528/10cf43debaea41fea3be9ebfdf13afa8.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 2]: /images/20230528/261ffc2250fb4e8ca11e14c1a69b441e.png