SpringBoot-如何设计优秀的后端接口?

1 概述

本篇文章以Spring Boot为基础，从以下三个方向讲述了如何设计一个优秀的后端接口体系：

• 参数校验：涉及Hibernate Validator的各种注解，快速失败模式，分组，组序列以及自定义注解/Validator
• 异常处理：涉及ControllerAdvice/@RestControllerAdvice以及@ExceptionHandler
• 数据响应：涉及如何设计一个响应体以及如何包装响应体

有了一个优秀的后端接口体系，不仅有了规范，同时扩展新的接口也很容易，本文演示了如何从零一步步构建一个优秀的后端接口体系。

2 新建工程

打开熟悉的IDEA，选择依赖：

首先创建如下文件：

TestController.java：

@RestController
@RequestMapping("/")
@CrossOrigin(value = "http://localhost:3000")
@RequiredArgsConstructor(onConstructor = @__(@Autowired))
public class TestController {
    private final TestService service;
    @PostMapping("test")
    public String test(@RequestBody User user)
    {
        return service.test(user);
    }
}

使用了@RequiredArgsConstructor代替@Autowired，由于笔者使用Postwoman测试，因此需要加上跨域注解@CrossOrigin，默认3000端口（Postwoman端口）。

TestService.java：

@Service
public class TestService {
    public String test(User user)
    {
        if(StringUtils.isEmpty(user.getEmail()))
            return "邮箱不能为空";
        if(StringUtils.isEmpty(user.getPassword()))
            return "密码不能为空";
        if(StringUtils.isEmpty(user.getPhone()))
            return "电话不能为空";
//        持久化操作
        return "success";
    }
}

业务层首先进行了参数校验，这里省略了持久化操作。

User.java：

@Data
public class User {
    private String phone;
    private String password;
    private String email;
}

3 参数校验

首先来看一下参数校验，上面的例子中在业务层完成参数校验，这是没有问题的，但是，还没进行业务操作就需要进行这么多的校验显然这不是很好，更好的做法是，使用Hibernate Validator。

3.1 Hibernate Validator

3.1.1 介绍

JSR是Java Specification Requests的缩写，意思是Java规范提案，是指向JCP(Java Community Process)提出新增一个标准化技术规范的正式请求。JSR-303是Java EE6中的一项子规范，叫作Bean Validation，Hibernate Validator是Bean Validator的参考实现，除了实现所有JSR-303规范中的内置constraint实现，还有附加的constraint，详细如下：

• @Null：被注解元素必须为null（为了节省篇幅下面用“元素”代表“被注解元素必须为”）
• @NotNull：元素不为null
• @AssertTrue：元素为true
• @AssertFalse：元素为false
• @Min(value)：元素大于或等于指定值
• @Max(value)：元素小于或等于指定值
• @DecimalMin(value)：元素大于指定值
• @DecimalMax(value)：元素小于指定值
• @Size(max,min)：元素大小在给定范围内
• @Digits(integer,fraction)：元素字符串中的整数位数规定最大integer位，小数位数规定最大fraction位
• @Past：元素是一个过去日期
• @Future：元素是将来日期
• @Pattern：元素需要符合正则表达式

其中Hibernate Validator附加的constraint如下：

• @Eamil：元素为邮箱
• @Length：字符串大小在指定范围内
• @NotEmpty：字符串必须非空（目前最新的6.1.5版本已弃用，建议使用标准的@NotEmpty）
• @Range：数字在指定范围内

而在Spring中，对Hibernate Validation进行了二次封装，添加了自动校验，并且校验信息封装进了特定的BindingResult中。下面看看如何使用。

3.1.2 使用

在各个字段加上@NotEmpty，并且邮箱加上@Email，电话加上11位限制，并且在各个注解加上message，表示对应的提示信息：

@Data
public class User {
    @NotEmpty(message = "电话不能为空")
    @Length(min = 11,max = 11,message = "电话号码必须11位")
    private String phone;
    @NotEmpty(message = "密码不能为空")
    @Length(min = 6,max = 20,message = "密码必须为6-20位")
    private String password;
    @NotEmpty(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;
}

对于String来说有时候会使用@NotNull或@NotBlank，它们的区别如下：

• @NotEmpty：不能为null并且长度必须大于0，除了String外，对于Collection/Map/数组也适用
• @NotBlank：只用于String，不能为null，并且调用trim()后，长度必须大于0，也就是必须有除空格外的实际字符
• @NotNull：不能为null

接着把业务层的参数校验操作删除，并把控制层修改如下：

@PostMapping("test")
public String test(@RequestBody @Valid User user, BindingResult bindingResult)
{
    if(bindingResult.hasErrors())
    {
        for(ObjectError error:bindingResult.getAllErrors())
            return error.getDefaultMessage();
    }
    return service.test(user);
}

在需要校验的对象上加上@Valid，并且加上BindingResult参数，可以从中获取错误信息并返回。

3.1.3 测试

全部都使用错误的参数设置，返回”邮箱格式不正确“：

第二次测试中除了密码都使用正确的参数，返回”密码必须为6-20位“：

第三次测试全部使用正确的参数，返回”success“：

3.2 校验模式设置

Hibernate Validator有两种校验模式：

• 普通模式：默认模式，会校验所有属性，然后返回所有的验证失败信息
• 快速失败模式：只要有一个验证失败就返回

使用快速失败模式需要通过HibernateValidateConfiguration以及ValidateFactory创建Validator，并且使用Validator.validate()进行手动验证。

首先添加一个生成Validator的类：

@Configuration
public class FailFastValidator<T> {
    private final Validator validator;
    public FailFastValidator()
    {
        validator = Validation
        .byProvider(HibernateValidator.class).configure()
		.failFast(true).buildValidatorFactory()
		.getValidator();
    }

    public Set<ConstraintViolation<T>> validate(T user)
    {
        return validator.validate(user);
    }
}

修改控制层的代码，通过@RequiredArgsConstructor注入FailFastValidator，并把原来的在User上的@Valid去掉，在方法体进行手动验证：

@RequiredArgsConstructor(onConstructor = @__(@Autowired))
public class TestController {
    private final TestService service;
    private final FailFastValidator<User> validator;
    @PostMapping("test")
    public String test(@RequestBody User user, BindingResult bindingResult)
    {
        Set<ConstraintViolation<User>> message = validator.validate(user);
        message.forEach(t-> System.out.println(t.getMessage()));
//        if(bindingResult.hasErrors())
//        {
//            bindingResult.getAllErrors().forEach(t->System.out.println(t.getDefaultMessage()));
//            for(ObjectError error:bindingResult.getAllErrors())
//                return error.getDefaultMessage();
//        }
        return service.test(user);
    }
}

测试（连续三次校验的结果）：

如果是普通模式（修改.failFast(false)），一次校验便会连续输出三个信息：

3.3 @Valid与@Validated

@Valid是javax.validation包里面的，而@Validated是org.springframework.validation.annotation里面的，是@Valid的一次封装，相当于是@Valid的增强版，供Spring提供的校验机制使用，相比起@Valid，@Validated提供了分组以及组序列的功能。下面分别进行介绍。

3.4 分组

当需要在不同的情况下使用不同的校验方式时，可以使用分组校验。比如在注册时不需要校验id，修改信息时需要校验id，但是默认的校验方式在两种情况下全部都校验，这时就需要使用分组校验。

下面以不同的组别校验电话号码长度的不同进行说明，修改User类如下：

@Data
public class User {
    @NotEmpty(message = "电话不能为空")
    @Length(min = 11,max = 11,message = "电话号码必须11位",groups = {GroupA.class})
    @Length(min = 12,max = 12,message = "电话号码必须12位",groups = {GroupB.class})
    private String phone;
    @NotEmpty(message = "密码不能为空")
    @Length(min = 6,max = 20,message = "密码必须为6-20位")
    private String password;
    @NotEmpty(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;

    public interface GroupA{}
    public interface GroupB{}
}

在@Length中加入了组别，GroupA表示电话需要为11位，GroupB表示电话需要为12位，GroupA/GroupB是User中的两个空接口，然后修改控制层：

public String test(@RequestBody @Validated({User.GroupB.class}) User user, BindingResult bindingResult)
{
    if(bindingResult.hasErrors())
    {
        bindingResult.getAllErrors().forEach(t->System.out.println(t.getDefaultMessage()));
        for(ObjectError error:bindingResult.getAllErrors())
            return error.getDefaultMessage();
    }
    return service.test(user);
}

在@Validated中指定为GroupB，电话需要为12位，测试如下：

3.5 组序列

默认情况下，不同组别的约束验证的无序的，也就是说，对于下面的User类：

@Data
public class User {
    @NotEmpty(message = "电话不能为空")
    @Length(min = 11,max = 11,message = "电话号码必须11位")
    private String phone;
    @NotEmpty(message = "密码不能为空")
    @Length(min = 6,max = 20,message = "密码必须为6-20位")
    private String password;
    @NotEmpty(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;
}

每次进行校验的顺序不同，三次测试结果如下：

有些时候顺序并不重要，而有些时候顺序很重要，比如：

• 第二个组中的约束验证依赖于一个稳定状态运行，而这个稳定状态由第一个组来进行验证
• 某个组的验证比较耗时，CPU和内存的使用率相对较大，最优的选择是将其放在最后进行验证

因此在进行组验证的时候需要提供一种有序的验证方式，一个组可以定义为其他组的序列，这样就可以固定每次验证的顺序而不是随机顺序，另外如果验证组序列中，前面的组验证失败，则后面的组不会验证。

例子如下，首先修改User类并定义组序列：

@Data
public class User {
    @NotEmpty(message = "电话不能为空",groups = {First.class})
    @Length(min = 11,max = 11,message = "电话号码必须11位",groups = {Second.class})
    private String phone;
    @NotEmpty(message = "密码不能为空",groups = {First.class})
    @Length(min = 6,max = 20,message = "密码必须为6-20位",groups = {Second.class})
    private String password;
    @NotEmpty(message = "邮箱不能为空",groups = {First.class})
    @Email(message = "邮箱格式不正确",groups = {Second.class})
    private String email;

    public interface First{}
    public interface Second{}
    @GroupSequence({First.class,Second.class})
    public interface Group{}
}

定义了两个空接口First和Second表示顺序，同时在Group中使用@GroupSequence指定了顺序。

接着修改控制层，在@Validated中定义组：

public String test(@RequestBody @Validated({User.Group.class}) User user, BindingResult bindingResult)

这样就能按照固定的顺序进行参数校验了。

3.6 自定义校验

尽管Hibernate Validator中的注解适用情况很广了，但是有时候需要特定的校验规则，比如密码强度，人为判定弱密码还是强密码。也就是说，此时需要添加自定义校验的方式，有两种处理方法：

• 自定义注解
• 自定义Validator

首先来看一下自定义注解的方法。

3.6.1 自定义注解

这里添加一个判定弱密码的注解WeakPassword：

@Documented
@Constraint(validatedBy = WeakPasswordValidator.class)
@Target({ElementType.METHOD,ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface WeakPassword{
    String message() default "请使用更加强壮的密码";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

同时添加一个实现了ConstraintValidator的WeakPasswordValidator，当密码长度大于10位时才符合条件，否则返回false表示校验不通过：

public class WeakPasswordValidator implements ConstraintValidator<WeakPassword,String> {
    @Override
    public boolean isValid(String s, ConstraintValidatorContext constraintValidatorContext) {
        return s.length() > 10;
    }
    @Override
    public void initialize(WeakPassword constraintAnnotation) {}
}

接着可以修改User如下，在对应的字段加上自定义注解@WeakPassword：

@Data
public class User {
	//...
    @WeakPassword(groups = {Second.class})
    private String password;
    //...
}

测试如下：

3.6.2 自定义Validator

除了自定义注解之外，还可以自定义Validator来实现自定义的参数校验，需要实现Validator接口：

@Component
public class WeakPasswordValidator implements Validator{
    @Override
    public boolean supports(Class<?> aClass) {
        return User.class.equals(aClass);
    }

    @Override
    public void validate(Object o, Errors errors) {
        ValidationUtils.rejectIfEmpty(errors,"password","password.empty");
        User user = (User)o;
        if(user.getPassword().length() <= 10)
            errors.rejectValue("password","Password is not strong enough!");
    }
}

实现其中的supports以及validate：

• support：可以验证该类是否是某个类的实例
• validate：当supports返回true后，验证给定对象o，当出现错误时，向errors注册错误

ValidationUtils.rejectIfEmpty校验当对象o中某个字段属性为空时，向其中的errors注册错误，注意并不会中断语句的运行，也就是即使password为空，user.getPassword()还是会运行，这时会抛出空指针异常。下面的errors.rejectValue同样道理，并不会中断语句的运行，只是注册了错误信息，中断的话需要手动抛出异常。

修改控制层中的返回值，改为getCode()：

if(bindingResult.hasErrors())
{
    bindingResult.getAllErrors().forEach(t-> System.out.println(t.getCode()));
    for(ObjectError error:bindingResult.getAllErrors())
        return error.getCode();
}
return service.test(user);

测试：

4 异常处理

到这里参数校验就完成了，下一步是处理异常。

如果将参数校验中的BindingResult去掉，就会将整个后端异常返回给前端：

//public String test(@RequestBody @Validated({User.Group.class}) User user, BindingResult bindingResult)
public String test(@RequestBody @Validated({User.Group.class}) User user)

这样虽然后端是方便了，不需要每一个接口都加上BindingResult，但是前端不好处理，整个异常都返回了，因此后端需要捕捉这些异常，但是，不能手动去捕捉每一个，这样还不如之前使用BindingResult，这种情况下就需要用到全局的异常处理。

4.1 基本使用

处理全局异常的步骤如下：

• 创建全局异常处理的类：加上@ControllerAdvice/@RestControllerAdvice注解（取决于控制层用的是@Controller/@RestController，@Controller可以跳转到相应页面，返回JSON等加上@ResponseBody即可，而@RestController相当于@Controller+@ResponseBody，返回JSON无需加上@ResponseBody，但是视图解析器无法解析jsp以及html页面）
• 创建异常处理方法：加上@ExceptionHandler指定想要处理的异常类型
• 处理异常：在对应的处理异常方法中处理异常

这里增加一个全局异常处理类GlobalExceptionHandler：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public String methodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e)
    {
        ObjectError error = e.getBindingResult().getAllErrors().get(0);
        return error.getDefaultMessage();
    }
}

首先加上@RestControllerAdvice，并在异常处理方法上加上@ExceptionHandler。

接着修改控制层，去掉其中的BindingResult：

@PostMapping("test")
public String test(@RequestBody @Validated({User.Group.class}) User user)
{
    return service.test(user);
}

然后就可以进行测试了：

全局异常处理相比起原来的每一个接口都加上BindingResult方便很多，而且可以集中处理所有异常。

4.2 自定义异常

很多时候都会用到自定义异常，这里新增一个测试异常TestException：

@Data
public class TestException extends RuntimeException{
    private int code;
    private String msg;

    public TestException(int code,String msg)
    {
        super(msg);
        this.code = code;
        this.msg = msg;
    }

    public TestException()
    {
        this(111,"测试异常");
    }

    public TestException(String msg)
    {
        this(111,msg);
    }
}

接着在刚才的全局异常处理类中添加一个处理该异常的方法：

@ExceptionHandler(TestException.class)
public String testExceptionHandler(TestException e)
{
    return e.getMsg();
}

在控制层进行测试：

@PostMapping("test")
public String test(@RequestBody @Validated({User.Group.class}) User user)
{
    throw new TestException("出现异常");
//        return service.test(user);
}

结果如下：

5 数据响应

在处理好了参数校验以及异常处理之后，下一步就是要设置统一的规范化的响应数据，一般来说无论响应成功还是失败都会有一个状态码，响应成功还会携带响应数据，响应失败则携带相应的失败信息，因此，第一步是设计一个统一的响应体。

5.1 统一响应体

统一响应体需要创建响应体类，一般来说，响应体需要包含：

• 状态码：String/int
• 响应信息：String
• 响应数据：Object/T（泛型）

这里简单的定义一个统一响应体Result：

@Data
@AllArgsConstructor
public class Result<T> {
    private String code;
    private String message;
    private T data;
}

接着修改全局异常处理类：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<String> methodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e)
    {
        ObjectError error = e.getBindingResult().getAllErrors().get(0);
        return new Result<>(error.getCode(),"参数校验失败",error.getDefaultMessage());
    }

    @ExceptionHandler(TestException.class)
    public Result<String> testExceptionHandler(TestException e)
    {
        return new Result<>(e.getCode(),"失败",e.getMsg());
    }
}

使用Result封装返回值，测试如下：

可以看到返回了一个比较友好的信息，无论是响应成功还是响应失败都会返回同一个响应体，当需要返回具体的用户数据时，可以修改控制层接口直接返回Result：

@PostMapping("test")
public Result<User> test(@RequestBody @Validated({User.Group.class}) User user)
{
    return service.test(user);
}

测试：

5.2 响应码枚举

通常来说可以把响应码做成枚举类：

@Getter
public enum ResultCode {
    SUCCESS("111","成功"),FAILED("222","失败");

    private final String code;
    private final String message;
    ResultCode(String code,String message)
    {
        this.code = code;
        this.message = message;
    }
}

枚举类封装了状态码以及信息，这样在返回结果时，只需要传入对应的枚举值以及数据即可：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<String> methodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e)
    {
        ObjectError error = e.getBindingResult().getAllErrors().get(0);
        return new Result<>(ResultCode.FAILED,error.getDefaultMessage());
    }

    @ExceptionHandler(TestException.class)
    public Result<String> testExceptionHandler(TestException e)
    {
        return new Result<>(ResultCode.FAILED,e.getMsg());
    }
}

5.3 全局包装响应体

统一响应体是个很好的想法，但是还可以再深入一步去优化，因为每次返回之前都需要对响应体进行包装，虽然只是一行代码但是每个接口都需要包装一下，这是个很麻烦的操作，为了更进一步“偷懒”，可以选择实现ResponseBodyAdvice来进行全局的响应体包装。

修改原来的全局异常处理类如下：

@RestControllerAdvice
public class GlobalExceptionHandler implements ResponseBodyAdvice<Object> {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<String> methodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e)
    {
        ObjectError error = e.getBindingResult().getAllErrors().get(0);
        return new Result<>(ResultCode.FAILED,error.getDefaultMessage());
    }

    @ExceptionHandler(TestException.class)
    public Result<String> testExceptionHandler(TestException e)
    {
        return new Result<>(ResultCode.FAILED,e.getMsg());
    }

    @Override
    public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
        return !methodParameter.getParameterType().equals(Result.class);
    }

    @Override
    public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
        return new Result<>(o);
    }
}

实现了ResponseBodyAdvice