SpringBoot 规范接口开发流程

笔记内容以及代码是我阅读了知乎作者RudeCrab的《【项目实践】SpringBoot三招组合拳，手把手教你打出优雅的后端接口》这篇文章后学习和总结的

原文链接: https://zhuanlan.zhihu.com/p/340620501

阶段一：Validator + BindResult进行校验

1. 引入validation依赖

Validation Starter no longer included in web starters
As of #19550, Web and WebFlux starters do not* depend on the validation starter by default anymore. If your application is using validation features, for example you find that javax.validation. imports are not being resolved, you'll need to add the starter yourself. For Maven builds, you can do that with the following:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

2. User实体类用Validator添加校验规则

Validator就是springboot的validation中的一些用于限制属性的注解

/**
 * 用户实体类
 */
@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 = 16, message = "账号长度必须是6-16个字符")
    private String password;

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

3. 给需要校验的参数加上@Valid注解

在Controller中的入参中，有要校验的实体类就给该参数加上@Valid注解即可使实体类中用@NotNull等validator相关注解生效
如果有参数校验失败，会将错误信息封装成对象组装在BindingResult里，即实体类中和validation相关的注解中的message属性会封装在这里

@RestController
@RequestMapping("user")
public class UserController {

    private UserService userService;

    @Autowired
    public void setUserService(UserService userService) {
        this.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);
    }
}

这样子的话校验规则就不用在service层去做了，将校验和业务逻辑处理分离，service只用单纯地处理业务，不需要担心字段的校验

UserService

@Service
public class UserServiceImpl implements UserService {
    @Override
    public String addUser(User user) {
        return "success";
    }
}

这种写法每次都要在controller层传入BindingResult，很不方便，接下来用自动抛出异常的方式去进一步优化

阶段二：Validator + 自动抛出异常

1. 把BindingResult去除

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

这时候后端已经引发了MethodArgumentNotValidException异常，并且前端收到的数据如下

{
    "timestamp": "2021-09-03T13:35:31.068+00:00",
    "status": 400,
    "error": "Bad Request",
    "trace": "...",
    "message": "Validation failed for object='user'. Error count: 3",
    "errors": [
        {
            "codes": [
                "Email.user.email",
                "Email.email",
                "Email.java.lang.String",
                "Email"
            ],
            "arguments": [
                {
                    "codes": [
                        "user.email",
                        "email"
                    ],
                    "arguments": null,
                    "defaultMessage": "email",
                    "code": "email"
                },
                [],
                {
                    "defaultMessage": ".*",
                    "codes": [
                        ".*"
                    ],
                    "arguments": null
                }
            ],
            "defaultMessage": "邮箱格式不正确",
            "objectName": "user",
            "field": "email",
            "rejectedValue": "975036719qq.com",
            "bindingFailure": false,
            "code": "Email"
        },
        {
            "codes": [
                "NotNull.user.password",
                "NotNull.password",
                "NotNull.java.lang.String",
                "NotNull"
            ],
            "arguments": [
                {
                    "codes": [
                        "user.password",
                        "password"
                    ],
                    "arguments": null,
                    "defaultMessage": "password",
                    "code": "password"
                }
            ],
            "defaultMessage": "用户密码不能为空",
            "objectName": "user",
            "field": "password",
            "rejectedValue": null,
            "bindingFailure": false,
            "code": "NotNull"
        },
        {
            "codes": [
                "NotNull.user.account",
                "NotNull.account",
                "NotNull.java.lang.String",
                "NotNull"
            ],
            "arguments": [
                {
                    "codes": [
                        "user.account",
                        "account"
                    ],
                    "arguments": null,
                    "defaultMessage": "account",
                    "code": "account"
                }
            ],
            "defaultMessage": "用户账号不能为空",
            "objectName": "user",
            "field": "account",
            "rejectedValue": null,
            "bindingFailure": false,
            "code": "NotNull"
        }
    ],
    "path": "/user/add-user"
}

后端直接将整个错误对象相关信息都响应给前端了，这是因为虽然引发了异常，但是我们没有去对其进行处理，所以走了SpringBoot默认的异常处理流程，现在开始进行全局异常处理

2. 全局异常处理

在类上加上@ControllerAdvice或@RestControllerAdvice注解，这个类就配置成全局处理类了

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

package com.plasticine.demo.config;

@RestControllerAdvice
public class ExceptionControllerAdvice {

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

3. 自定义异常

自定义异常的好处

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

自定义异常 -- APIException

package com.plasticine.demo.exception;

@Getter // 不需要 setter，需要抛出异常的时候都是直接 new 一个调用构造方法即可
public class APIException extends RuntimeException {
    private final int errcode;
    private final String errmsg;

    public APIException() {
        this(1001, "API Error");
    }

    public APIException(String errmsg) {
        this(1001, errmsg);
    }

    public APIException(int errcode, String errmsg) {
        this.errcode = errcode;
        this.errmsg = errmsg;
    }
}

还能在全局异常处理中处理Exception异常，这样无论遇到什么Exception都能够统一返回给前端，不过这种一般建议是在项目上线之前才这样做，开发的时候为了方便调试还是不太建议这样做

4. 数据统一响应

前面的处理异常的结果都是返回的错误信息，而没有返回别的比如errcode
为了更加统一，应当让异常和正常api数据请求的结果格式相同，都应该包括errcode、errmsg和data，因此需要自定义一个统一的响应体

自定义统一响应体（VO，即View Object，是后端向模板引擎渲染数据时传输的对象，也可以是返回JSON数据的统一对象）

package com.plasticine.demo.vo;

@Getter
public class ResultVO<T> {
    private final int errcode;    // api 响应状态码
    private final String errmsg;  // api 请求信息
    private final T data;         // api 返回的数据

    public ResultVO(T data) {
        this(ResultCode.SUCCESS, data);
    }

    public ResultVO(int errcode, String errmsg, T data) {
        this.errcode = errcode;
        this.errmsg = errmsg;
        this.data = data;
    }

    public ResultVO(ResultCode resultCode, T data) {
        this.errcode = resultCode.getErrcode();
        this.errmsg = resultCode.getErrmsg();
        this.data = data;
    }
}

修改全局异常处理的返回值类型为ResultVO

package com.plasticine.demo.config;

@RestControllerAdvice
public class ExceptionControllerAdvice {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResultVO<String> MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) {
        // 从异常中拿到 ObjectError 对象
        ObjectError error = e.getBindingResult().getAllErrors().get(0);
        // 提取错误信息返回
        return new ResultVO<String>(1001, "参数校验失败", error.getDefaultMessage());
    }

    /**
     * 统一全局处理自定义异常 APIException
     *
     * @param e APIException
     * @return 处理结果
     */
    @ExceptionHandler(APIException.class)
    public ResultVO<String> APIExceptionHandler(APIException e) {
        return new ResultVO<>(e.getErrcode(), "api请求失败", e.getErrmsg());
    }
}

现在遇到异常时返回的就会是JSON数据格式的字符串了

{
    "errcode": 1001,
    "errmsg": "参数校验失败",
    "data": "邮箱格式不正确"
}

修改Controller和Service返回值类型

service

public interface UserService {

    /**
     * 添加 user
     *
     * @param user User 实体类对象
     * @return 成功返回 success，失败返回错误信息
     */
    ResultVO<User> addUser(User user);
}

@Service
public class UserServiceImpl implements UserService {
    @Override
    public ResultVO<User> addUser(User user) {
        return new ResultVO<User>(user);
    }
}

controller

@RestController
@RequestMapping("user")
public class UserController {

    private UserService userService;

    @Autowired
    public void setUserService(UserService userService) {
        this.userService = userService;
    }

    @PostMapping("/add-user")
    public ResultVO<User> addUser(@RequestBody @Valid User user) {
        return userService.addUser(user);
    }
}

现在请求成功的api返回的数据也可以是自定义的了

请求体

{
    "id": 666,
    "account": "plasticine",
    "password": "abc123",
    "email": "975036719@qq.com"
}

响应体

{
    "errcode": 1000,
    "errmsg": "success",
    "data": {
        "id": 666,
        "account": "plasticine",
        "password": "abc123",
        "email": "975036719@qq.com"
    }
}

响应码枚举

响应码都是纯数字，不好理解errcode的意思，使用枚举可以解决这一问题

/**
 * errcode 枚举
 */
@Getter
public enum ResultCode {

    SUCCESS(1000, "操作成功"),
    FAILED(1001, "操作失败"),
    VALIDATE_FAILED(1002, "参数校验失败"),
    ERROR(5000, "未知错误");

    private int errcode;
    private String errmsg;

    ResultCode(int errcode, String errmsg) {
        this.errcode = errcode;
        this.errmsg = errmsg;
    }
}

修改全局异常处理的返回值

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResultVO<String> MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) {
    // 从异常中拿到 ObjectError 对象
    ObjectError error = e.getBindingResult().getAllErrors().get(0);
    // 提取错误信息返回
    return new ResultVO<>(ResultCode.VALIDATE_FAILED, error.getDefaultMessage());
}

@ExceptionHandler(APIException.class)
public ResultVO<String> APIExceptionHandler(APIException e) {
    return new ResultVO<>(ResultCode.FAILED, e.getErrmsg());
}

5. 全局处理响应数据

先创建一个类加上注解使其成为全局处理类
继承ResponseBodyAdvice接口重写其中的方法

package com.plasticine.demo.config;

@RestControllerAdvice(basePackages = {"com.plasticine.demo.controller"})
public class ResponseControllerAdvice implements ResponseBodyAdvice<Object> {

    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        /*
            返回 true 代表要走 beforeBodyWrite 方法去对返回结果进行额外处理
            反之，false 代表不走 beforeBodyWrite 方法，直接返回 returnType
            如果返回的类型是 ResultVO 则不需要进行额外操作，直接返回即可
         */
        return !returnType.getParameterType().equals(ResultVO.class);
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {

        // String 不能直接由 ResultVO 封装，要经过一些处理先
        if (returnType.getGenericParameterType().equals(String.class)) {
            ObjectMapper objectMapper = new ObjectMapper();
            try {
                return objectMapper.writeValueAsString(new ResultVO<>(body));
            } catch (JsonProcessingException e) {
                throw new APIException("返回 String 类型时封装出错");
            }
        }

        // 将原本的数据经 ResultVO 统一响应体封装后再返回
        return new ResultVO<>(body);
    }
}

写一个新的api，返回的类型不再是ResultVo，而是直接返回实体类对象，这样就会走beforeBodyWrite方法去包装，然后真正返回给前端的还是ResultVO，这样做的目的就是可以省去我们自己手动封装数据到ResultVO的过程

对比返回ResultVO和直接返回User实体类对象

/**
 * 返回的类型是 ResultVO 类型，不会经过 ResponseControllerAdvice 的 beforeBodyWrite 处理
 *
 * @param user 要添加的用户
 * @return 经过 ResultVO 封装的统一响应体
 */
@PostMapping("/add-user")
public ResultVO<User> addUser(@RequestBody @Valid User user) {
    return userService.addUser(user);
}

/**
 * 返回的类型是 User 不是 ResultVO 类型，会经过 ResponseControllerAdvice 的 beforeBodyWrite 处理
 * 将 user 封装进 ResultVO 的 data 属性中返回
 *
 * @return user 封装到 ResultVO 后的统一响应体
 */
@GetMapping("/get-user")
public User getUser() {
    return new User(666L, "plasticine", "abc123", "975036719@qq.com");
}

如果beforeBodyWrite()中不处理返回类型是String的情况会怎样呢？

@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
    return new ResultVO<>(body);
}

会遇到ClassCastException异常

java.lang.ClassCastException: com.plasticine.demo.vo.ResultVO cannot be cast to java.lang.String

阶段三：自定义注解实现绕过数据统一响应

前面的方案中，正常数据返回的状态码都是统一的，封装在enum状态码枚举中，这没什么问题

可是在异常的处理中，字段校验错误的状态码统一都是1002，如果想给每个字段自定义状态码以及错误信息时，就做不到了，这时就可以在要校验的字段上加上我们自定义的注解，然后通过反射来获取注解从而对每个字段的校验错误实现自定义错误码的功能

1. 自定义注解

package com.plasticine.demo.annotation;

/**
 * 自定义参数校验错误码以及错误信息注解
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})        // 作用在类的属性上
public @interface ExceptionCode {
    // 响应码 errcode
    int errcode() default 100000;
    // 响应信息 errmsg
    String errmsg() default "参数校验错误";
}

2. 给实体类中要自定义校验响应体的字段加上注解

package com.plasticine.demo.pojo;

/**
 * 用户实体类
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    @NotNull(message = "用户id不能为空")
    private Long id;

    @NotNull(message = "用户账号不能为空")
    @Size(min = 6, max = 11, message = "账号长度必须是6-11个字符")
    @ExceptionCode(errcode = 100001, errmsg = "账号不符合校验规则")
    private String account;

    @NotNull(message = "用户密码不能为空")
    @Size(min = 6, max = 16, message = "账号长度必须是6-16个字符")
    @ExceptionCode(errcode = 100002, errmsg = "密码不符合校验规则")
    private String password;

    @NotNull(message = "用户邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    @ExceptionCode(errcode = 100003, errmsg = "邮箱不符合校验规则")
    private String email;
}

3. 修改全局异常处理MethodArgumentNotValidException的代码

package com.plasticine.demo.config;

@RestControllerAdvice
public class ExceptionControllerAdvice {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResultVO<String> MethodArgumentNotValidExceptionHandler(MethodArgumentNotValidException e) throws NoSuchFieldException {
        // 从异常对象中拿到错误信息
        String defaultMessage = e.getBindingResult().getAllErrors().get(0).getDefaultMessage();
        // 获取参数的 Class 对象，从而获取到 Field 对象，便可以拿到自定义的注解内容了
        Class<?> parameterType = e.getParameter().getParameterType();
        // 拿到错误字段名称，然后根据错误字段名获取到 Field 对象
        String fieldName = e.getBindingResult().getFieldError().getField();
        Field field = parameterType.getDeclaredField(fieldName);
        // 获取 Field 的自定义注解
        ExceptionCode annotation = field.getAnnotation(ExceptionCode.class);
        // 有注解则用注解中自定义的 errcode 和 errmsg 作为统一响应体返回
        if (annotation != null) {
            return new ResultVO<>(annotation.errcode(), annotation.errmsg(), defaultMessage);
        }

        // 没有使用自定义注解的字段则用枚举中的 VALIDATE_FAILED 进行统一返回
        return new ResultVO<>(ResultCode.VALIDATE_FAILED, defaultMessage);
    }
}

效果

上面实体类中，id字段没有加上自定义注解，所以会走统一的VALIDATE_FAILED封装的响应体，而其他字段都加上了自定义注解，所以遇到字段校验出错时就会用自定义注解中的errcode和errmsg去封装返回

id为空

// 请求体
{
    "account": "plasticine",
    "password": "abc123",
    "email": "975036719@qq.com"
}

// 响应体
{
    "errcode": 1002,
    "errmsg": "参数校验失败",
    "data": "用户id不能为空"
}

account为空

// 请求体
{
    "id": 666,
    "password": "abc123",
    "email": "975036719@qq.com"
}

// 响应体
{
    "errcode": 100001,
    "errmsg": "账号不符合校验规则",
    "data": "用户账号不能为空"
}

4. 绕过数据统一响应

上面返回的响应体都是经过ResultVO封装过的，如果不想用ResultVO封装，而是自定义返回数据的格式，也就是要绕过数据统一响应，那可以给要绕过统一响应的方法加上一个自定义注解，然后在统一处理的部分对有该注解的方法不进行封装处理

自定义绕过统一响应注解

package com.plasticine.demo.annotation;

/**
 * 绕过统一数据响应
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface BypassResultVO {
}

修改ResponseControllerAdvice

package com.plasticine.demo.config;

@RestControllerAdvice(basePackages = {"com.plasticine.demo.controller"})
public class ResponseControllerAdvice implements ResponseBodyAdvice<Object> {

    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        /*
            返回 true 代表要走 beforeBodyWrite 方法去对返回结果进行额外处理
            反之，false 代表不走 beforeBodyWrite 方法，直接返回 returnType
            如果返回的类型是 ResultVO 则不需要进行额外操作，直接返回即可
         */
        if (returnType.getParameterType().equals(ResultVO.class)) return false;     // 返回类型已经是 ResultVO，不需要经过额外处理
        if (returnType.hasMethodAnnotation(BypassResultVO.class)) return false;     // 加上了 @BypassResultVO 注解，不需要经过额外处理

        return true;
    }
}

即在supports()中加上returnType.hasMethodAnnotation(BypassResultVO.class);即可，也就是说有BypassResultVO这个注解的方法就不走beforeBodyWrite()方法处理

测试：给getUser()加上BypassResultVO

@GetMapping("/get-user")
@BypassResultVO
public User getUser() {
    return new User(666L, "plasticine", "abc123", "975036719@qq.com");
}

未加上@BypassResultVO注解之前的响应体：

{
    "errcode": 1000,
    "errmsg": "操作成功",
    "data": {
        "id": 666,
        "account": "plasticine",
        "password": "abc123",
        "email": "975036719@qq.com"
    }
}

加上注解后：

{
    "id": 666,
    "account": "plasticine",
    "password": "abc123",
    "email": "975036719@qq.com"
}

最后编辑于：2021.09.04 21:22:40

人面猴
序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
沈念sama阅读 157,012评论 4赞 359
死咒
序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
沈念sama阅读 66,589评论 1赞 290
救了他两次的神仙让他今天三更去死
文/潘晓璐我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
开封第一讲书人阅读 106,819评论 0赞 237
道士缉凶录：失踪的卖姜人
文/不坏的土叔我叫张陵，是天一观的道长。经常有香客问我，道长，这世上最难降的妖魔是什么？我笑而不...
开封第一讲书人阅读 43,652评论 0赞 202
港岛之恋（遗憾婚礼）
正文为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
茶点故事阅读 51,954评论 3赞 285
恶毒庶女顶嫁案：这布局不是一般人想出来的
文/花漫我一把揭开白布。她就那样静静地躺着，像睡着了一般。火红的嫁衣衬着肌肤如雪。梳的纹丝不乱的头发上，一...
开封第一讲书人阅读 40,381评论 1赞 210
城市分裂传说
那天，我揣着相机与录音，去河边找鬼。笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。我是一名探鬼主播，决...
沈念sama阅读 31,687评论 2赞 310
双鸳鸯连环套：你想象不到人心有多黑
文/苍兰香墨我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
开封第一讲书人阅读 30,404评论 0赞 194
万荣杀人案实录
序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
沈念sama阅读 34,082评论 1赞 238
护林员之死
正文独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋以下内容为张勋视角年9月15日...
茶点故事阅读 30,355评论 2赞 241
白月光启示录
正文我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
茶点故事阅读 31,880评论 1赞 255
活死人
序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
沈念sama阅读 28,249评论 2赞 250
日本核电站爆炸内幕
正文年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
茶点故事阅读 32,864评论 3赞 232
男人毒药：我在死后第九天来索命
文/蒙蒙一、第九天我趴在偏房一处隐蔽的房顶上张望。院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
开封第一讲书人阅读 26,007评论 0赞 8
一桩弑父案，背后竟有这般阴谋
文/苍兰香墨我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。一阵脚步声响...
开封第一讲书人阅读 26,760评论 0赞 192
情欲美人皮
我被黑心中介骗来泰国打工，没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。一个月前我还...
沈念sama阅读 35,394评论 2赞 269
代替公主和亲
正文我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
茶点故事阅读 35,281评论 2赞 259