SpringBoot！你的请求、响应、异常规范了吗？

墨蓝 2022-12-27 02:13 125阅读 0赞

![image-20201207014448887][]

### 文章目录 ###

*   *   *   *  前言
             *  问题点
             *   *  请求
                 *  响应
                 *  异常
             *  hibernate-validator优雅的处理请求
             *   *  疑问
                 *  hibernate-validator
                 *   *  优点
                     *  注解说明
                     *  如何简单使用？
                     *  请求对象的合并
                     *  自定义校验
             *  响应
             *   *  疑问
                 *  响应格式规范
                 *  纯枚举的错误码定义（不采取）
                 *  可扩展性状态码
                 *  公共响应对象定义
                 *  响应数据初始化工具
                 *  使用JsonView；规范响应对象
                 *  如何统一返回包装对象
             *  异常
             *   *  定义业务异常
                 *  如何优雅的全局捕获异常
             *  总结

#### 前言 ####

这段时间在调整老系统相关的一些业务代码；发现一些模块，在无形中就被弄的有点乱了，由于每个开发人员技术水平不同、编码习惯差异；从而导致在请求、响应、异常这一块儿，出现了一些比较别扭的代码；但是归根究底，主要问题还是出在规范上面；不管是大到项目还是小到功能模块，对于请求、响应、异常这一块儿，应该是一块儿公共的模板化的代码，一旦定义清楚之后，是不需要做任何改动，而且业务开发过程中，也几乎是不需要动到他丝毫；所以，一个好的规范下，是不应该在这部分代码上出现混乱或者别扭的情况的；忍不住又得来整理一下这一块儿的东西；

作为一个后台的工程师，**接受请求、处理业务、解决异常、响应数据**，几乎覆盖了日常开发的全部；但是这个中间，除了**业务代码**是不可避免且无可替代之外；其他的三项操作，不管是啥功能，也都是大同小异的，那我们要如何来把这一块儿的东西抽离出来，让我们只需要去管业务，不用去管那些杂七杂八的的破事儿，从而腾出更多的时间学(mo)习(yu)呢？当然就是得去定义一个好的规则，运用优秀的轮子；让这部分重复的、可复用的工作给**模板化、标准化**；

这样，开发一遍，后面就不需要再去弄这些通用的东西了。

思考一下，关于请求、响应、异常，我们到底要注意些啥问题呢？

#### 问题点 ####

##### 请求 #####

1.  如何优雅的`接受`数据？
2.  如何优雅的`校验`数据？

##### 响应 #####

1.  响应数据格式`如何统一`？
2.  错误码如何`规范`？
3.  如何将业务功能和响应给`剥离`开来？

##### 异常 #####

1.  异常如何`捕获`？
2.  业务异常、校验异常如何合理的转换为友好的`标准响应`？
3.  如何规避未捕获到的异常并优雅返回标准响应？

这一些列的问题，就衍生出，我们该如何去规范的问题？任何利用已有的优秀框架去解决这些问题？

接下来，就通过一个完整的示例，基于这三个大点下面的小问题，去把这个规范给讲清楚；

示例源码地址: https://github.com/183619962/springcloud-mbb/tree/main/springboot-valid

> 讲每个大的问题点之前，我会给大家一个或几个疑问；然后可以带着这些疑问，边思考边看。
> 
> 下面的介绍，我们就以一个简单的用户信息(UserInfo)的CURD展开

#### hibernate-validator优雅的处理请求 ####

##### 疑问 #####

1.  `我们要如何去校验请求的数据？`
2.  `相同的对象去接受不同请求数据，如何能区别校验？`
    
    > 主要的目的是为了减少一些非必要的DTO对象

如果我们要去做用户的添加和修改，我们会如何去写请求参数的接受？

@RestController
    @RequestMapping("user")
    public class UserController{ 
    
        @PostMapping("add")
        public String add(@RequestBody UserAddRequestDto addInfo){ 
            // ......
            return "ok";
        }
    
        @PutMapping("update")
        public void update(@RequestBody UserUpdateRequestDto updateInfo)
        { 
            // ......
            return "ok";
        }
    }

这样？嗯！这样确实可以接受到请求参数，但是我们回归到上面的疑问；

参数如何校验？难道这样？

if(null==addInfo.getUserName()){ 
    	throw new Exceprion();
    }
    if(null==addInfo.getPassWord()){ 
    	throw new Exceprion();
    }
    // 。。。。

固然可以，这样真的好吗？很明显不好。。。。劳力伤神的事儿，咱可不干。

addInfo和updateInfo大部分属性都是一样的，添加的字段，大部分都是可以进行修改的，但是也有部分是不可以修改的；比如密码，一般都是单独写接口进行修改；

既然大部分都一样；有必要定义这么多个请求的DTO对象吗？有必要！！没办法啊！大部分一样，他也有不一样的地方！

那有没有能优雅的去解决参数校验问题，又可以将请求对象合多为一呢？

[hibernate-validator][]就是一个可以完美的解决这些问题的优秀框架；

接下来，我们就详细的来看一下，如何使用这个工具。

##### hibernate-validator #####

###### 优点 ######

*  `解耦`，数据的校验与业务逻辑进行分离，降低耦合度
    
    > 到controller的对象就已经是校验过的对象了，接受到之后就只需要安心处理业务就好，不用再进行数据校验相关逻辑
 *  `规范的校验方式`，减少参数校验所带来的繁琐体力活
    
    > 以注解的方式配置校验规则；大大减少校验的工作量，而且复用性强
 *  `简洁代码`，提高代码的可读性
    
    > 以注解方式即可完成属性校验，去掉了各种冗长的校验代码；且所有的校验规则都定义在对象内部；使得代码结构更加清晰，可读性非常强。

###### 注解说明 ######

> 下面包含了validator的所有内置的注解

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@AssertFalse</td> 
   <td>被注释的元素必须为 false</td> 
  </tr> 
  <tr> 
   <td>@AssertTrue</td> 
   <td>被注释的元素必须为 true</td> 
  </tr> 
  <tr> 
   <td>@DecimalMin(value)</td> 
   <td>被注释的元素必须是一个数字，其值必须大于等于指定的最小值</td> 
  </tr> 
  <tr> 
   <td>@DecimalMax(value)</td> 
   <td>被注释的元素必须是一个数字，其值必须小于等于指定的最大值</td> 
  </tr> 
  <tr> 
   <td>@Digits (integer, fraction)</td> 
   <td>被注释的元素必须是一个数字，其值必须在可接受的范围内</td> 
  </tr> 
  <tr> 
   <td>@Email</td> 
   <td>被注释的元素必须是电子邮箱地址</td> 
  </tr> 
  <tr> 
   <td>@Future</td> 
   <td>被注释的元素必须是一个将来的日期</td> 
  </tr> 
  <tr> 
   <td>@Length(min=,max=)</td> 
   <td>被注释的字符串的大小必须在指定的范围内</td> 
  </tr> 
  <tr> 
   <td>@Min(value)</td> 
   <td>被注释的元素必须是一个数字，其值必须大于等于指定的最小值</td> 
  </tr> 
  <tr> 
   <td>@Max(value)</td> 
   <td>被注释的元素必须是一个数字，其值必须小于等于指定的最大值</td> 
  </tr> 
  <tr> 
   <td>@Negative</td> 
   <td>该值必须小于0</td> 
  </tr> 
  <tr> 
   <td>@NegativeOrZero</td> 
   <td>该值必须小于等于0</td> 
  </tr> 
  <tr> 
   <td>@Null</td> 
   <td>被注释的元素必须为 null</td> 
  </tr> 
  <tr> 
   <td>@NotNull</td> 
   <td>被注释的元素必须不为 null</td> 
  </tr> 
  <tr> 
   <td>@NotBlank(message =)</td> 
   <td>验证字符串非null，且长度必须大于0</td> 
  </tr> 
  <tr> 
   <td>@NotEmpty</td> 
   <td>被注释的字符串的必须非空</td> 
  </tr> 
  <tr> 
   <td>@Past</td> 
   <td>被注释的元素必须是一个过去的日期</td> 
  </tr> 
  <tr> 
   <td>@Pattern(regex=,flag=)</td> 
   <td>被注释的元素必须符合指定的正则表达式</td> 
  </tr> 
  <tr> 
   <td>@Positive</td> 
   <td>该值必须大于0</td> 
  </tr> 
  <tr> 
   <td>@PositiveOrZero</td> 
   <td>该值必须大于等于0</td> 
  </tr> 
  <tr> 
   <td>@Range(min=,max=,message=)</td> 
   <td>被注释的元素必须在合适的范围内</td> 
  </tr> 
  <tr> 
   <td>@Size(max=, min=)</td> 
   <td>数组大小必须在[min,max]这个区间</td> 
  </tr> 
  <tr> 
   <td>@URL(protocol=,host,port)</td> 
   <td>检查是否是一个有效的URL，如果提供了protocol，host等，则该URL还需满足提供的条件</td> 
  </tr> 
  <tr> 
   <td>@Valid</td> 
   <td>该注解主要用于字段为一个包含其他对象的集合或map或数组的字段，或该字段直接为一个其他对象的引用，这样在检查当前对象的同时也会检查该字段所引用的对象</td> 
  </tr> 
 </tbody> 
</table>

###### 如何简单使用？ ######

*  第一步；引入依赖
    
        <dependency>
           <groupId>org.hibernate.validator</groupId>
           <artifactId>hibernate-validator</artifactId>
        </dependency>
 *  第二步；属性添加对应的注解
    
    > 按照上面表格的说明，根据自己定义`属性的特点，添加相应的注解`。
    > 
    > 如下示例，用户名，密码，年龄不能为空；那我们就用@NotBlank @NotNull去修饰，如果违背规则，就会按message的文本提示
    > 
    > 年龄不能小于0岁、大于120岁；那么就用@min @max进行约束
    > 
    > message描述了违背校验规则之后的描述。
    
        @Data
        public class UserRequestDto { 
            /** * 用户名 */
            @NotBlank(message = "姓名不能为空")
            public String userName;
        
            /** * 密码 */
            @NotBlank(message = "密码不能为空")
            public String passWord;
        
            /** * 年龄 */
            @NotNull(message = "年龄不能为空")
            @Min(value = 0,message = "年龄不能小于0岁")
            @Max(value = 120,message = "年龄不能大于120岁")
            private Integer age;
            
            /** * 手机号码；使用正则进行匹配 */
            @NotBlank(message = "手机号码不能为空")
            @Pattern(regexp = "^((13[0-9])|(14[5,7])|(15[0-3,5-9])|(17[0,3,5-8])|(18[0-9])|166|198|199|(147))\\d{8}$", message = "号码格式不正确!")
            private String phoneNum;
        	
            // 。。。。
        }
 *  第三步，Controller的参数加上@Validated
    
        @PostMapping("add")
        public BaseResponceDto add(@Validated @RequestBody UserRequestDto userRequestDto) { 
        	// 。。。。
        }
 *  第四步，测试
    
    > 加上validate之后，再次请求的时候，就会出现以下的错误
    > 
    > 由于太长，只截取了部分；可以看出，在接受到请求，处理业务之前，就已经报错了，并提示了对应的message信息；
    > 
    > 前端也收到了400的错误码
    
        Resolved [org.springframework.web.bind.MethodArgumentNotValidException: Validation failed for argument [0] in public com.lupf.springbootvalid.dto.UserResponceDto ..... default message [userName]]; default message [姓名不能为空]] ..... ]
    
    ![image-20201201231837804][]
 *  第五步，异常处理
    
    上面的操作可以看出，当请求参数如果不符合条件的话，就已经抛出异常并响应客户端了；
    
    但是异常并没有针对性的处理，也没有进行友好的提示；前端收到错误之后，没办法根据错误信息准确的判断出是什么问题；因此对于的异常还需要进行特殊处理；具体的处理方式，会在后续讲解异常的时候说到，这里暂时不展开，可以继续往后看。

上面我们已经将请求的参数以一种比较优雅的方式给验证了；但是并没有将请求对象合并，依然还是使用的addInfo和updateInfo对参数进行接受的；下面就一起来看一下，如何将这边同质化的对象进行优雅的合并。

###### 请求对象的合并 ######

*  **group说明**
    
    上面的业务场景中添加和修改用户信息，添加的时候，密码字段是必传的；修改的时候，密码是不需要传的；那我们能否把添加和修改所有用到的属性定义到一个对象中，然后根据不同的请求，去校验参数，比如，调用添加接口，密码是必传的；调用修改接口，就不需要传密码；为了能做到接口区分校验，就可以用到group这个关键参数；
 *  **group的理解**
    
    可以简单的理解就是把各个属性进行分组；校验的时候，会根据当前Controller指定的组进行校验，这些组里面包含了那些属性，就只校验那些属性，其他不在范围内的，就直接给忽略调掉。
 *  **group定义**
    
    group的定义是`以接口为基本单元`；也就是一个接口代表一个组；
 *  使用示例
    
     *  定义基础的、修改、添加的接口（group）
        
            // 基础的校验接口，标识着所有操作都需要校验的字段
            public interface UserRequestDtoSimpleValidate { };
            
            // 修改的校验；继承自UserRequestDtoSimpleValidate 
            // 也就是说指定为这个组的时候在满足当前校验规则的同时还得校验simple接口的属性
            public interface UserRequestDtoUpdateValidate extends UserRequestDtoSimpleValidate { }
            
            // 原理同上
            public interface UserRequestDtoAddValidate extends UserRequestDtoUpdateValidate { }
        
        ![image-20201201233848289][]
     *  属性校验添加上分组配置
        
            /** * 用户名 */
            @NotBlank(message = "姓名不能为空",groups = UserRequestDtoSimpleValidate.class)
            public String userName;
            
            /** * 密码 */
            @NotBlank(message = "密码不能为空",groups = UserRequestDtoAddValidate.class)
            public String passWord;
            
            /** * 年龄 */
            @NotNull(message = "年龄不能为空",groups = UserRequestDtoSimpleValidate.class)
            @Min(value = 0,message = "年龄不能小于0岁",groups = UserRequestDtoSimpleValidate.class)
            @Max(value = 120,message = "年龄不能大于120岁",groups = UserRequestDtoSimpleValidate.class)
            private Integer age;
            
            /** * 手机号码；使用正则进行匹配 */
            @NotBlank(message = "手机号码不能为空",groups = UserRequestDtoAddValidate.class)
            @Pattern(regexp = "^((13[0-9])|(14[5,7])|(15[0-3,5-9])|(17[0,3,5-8])|(18[0-9])|166|198|199|(147))\\d{8}$", message = "号码格式不正确!",groups = UserRequestDtoAddValidate.class)
            private String phoneNum;
            
            // 。。。。
     *  Controller指定分组进行校验
        
        > 如下@Validated中，指定分组接口类；可以一个，也可以多个，这样就会按照指定的分组进行参数校验
        
            @PostMapping("add")
            public UserResponceDto add(@Validated(UserRequestDto.UserRequestDtoAddValidate.class) @RequestBody UserRequestDto userRequestDto) { 
                // 后续业务
            }
            
            @PutMapping("update")
            public void update(@Validated(UserRequestDto.UserRequestDtoUpdateValidate.class) @RequestBody UserRequestDto userRequestDto) throws BaseException { 
                // 后续业务
            }

###### 自定义校验 ######

上面的所有校验，全部使用的是内置的注解，实际的使用过程中，不可避免的有一些特殊的业务场景，参数规则太过于个性化，内置的注解无法满足我们的需求时，要怎么办？比如说，**文本必须全部是大写或者小写**（该需求其实也可以通过正则表达式的方式进行）；为了剧情需要，那我们可以基于这个需求，来自定义一个校验器；

*  定义大小写的枚举
    
    > 用于注解使用的时候，来指定是校验规则是大写的还是小写的
    
        public enum CaseMode { 
            //大写
            UPPER,
            //小写
            LOWER;
        }
 *  定义校验大小写的注解
    
        @Documented
        @Target({ ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
        @Retention(RetentionPolicy.RUNTIME)
        //指定校验器
        @Constraint(validatedBy = CaseCheckValidator.class)
        public @interface CaseCheck { 
            String message() default "";
        
            Class<?>[] groups() default { };
        
            Class<? extends Payload>[] payload() default { };
        
            CaseMode value() default CaseMode.UPPER;
        }
    
    这里面，我们将CaseMode枚举作为了注解中的value参数，可以根据需要**动态设置大小写**的参数，这里默认就是大写的；
    
    @Constraint(validatedBy = CaseCheckValidator.class) 指明的使用CaseCheckValidator这个校验器进行数据校验；具体的校验规则，判断逻辑，就是写在这个校验器里面。
 *  自定义校验器
    
        public class CaseCheckValidator implements ConstraintValidator<CaseCheck, String> { 
            //大小写的枚举
            private CaseMode caseMode;
        
            @Override
            public void initialize(CaseCheck caseCheck) { 
                this.caseMode = caseCheck.value();
            }
        
            @Override
            public boolean isValid(String value, ConstraintValidatorContext context) { 
                //如果文本是空,则不进行校验，因为有其他的注解是可以校验空或者空字符串的
                if (null == value) { 
                    return true;
                }
        
                //文本只能是字母的正则
                String pattern = "^[a-zA-Z]*$";
                //校验传进来的是否是只包含了字母的文本
                boolean isMatch = Pattern.matches(pattern, value);
                //如果存在其他字符则返回校验失败
                if (!isMatch) { 
                    return false;
                }
        
                //如果没有指定方式，则直接返回false
                if (null == caseMode) { 
                    return false;
                }
        
                //判断是否符合大小写条件
                if (caseMode == CaseMode.UPPER) { 
                    return value.equals(value.toUpperCase());
                } else { 
                    return value.equals(value.toLowerCase());
                }
            }
        }
    
     *  **泛型说明**
        
        该校验器继承自`ConstraintValidator`这个接口；并传递了两个泛型参数；第一个是指明你`自定义的注解`；第二个是该注解作用的`属性类型`；
     *  **校验初始化**
        
        如果属性添加了该校验器对应的注解，就会初始化(`initialize`)该校验器时，将你加在属性上面的注解传递进来；
     *  **验证**
        
        \`初始化完会调用isValid方法·，并传递属性值；拿到属性值之后，就可以根据初始化传入的注解指定的规则，对属性值进行校验。验证通过返回true，并进行下一个属性的校验；验证失败返回false，并抛出异常；
 *  测试
    
        /** * 用户名 */
        @NotBlank(message = "姓名不能为空",groups = UserRequestDtoSimpleValidate.class)
        @CaseCheck(value = CaseMode.UPPER,message = "用户名必须大写字母",groups = UserRequestDtoSimpleValidate.class)
        public String userName;
        
        // 。。。。
    
    ![image-20201202230819477][]

--------------------

#### 响应 ####

##### 疑问 #####

1.  以什么样的格式返回数据？
    
    > 具体的格式，并没有一个绝对的标准，但是他必须满足一些条件：`格式统一，易于扩展`
2.  异常码如何规范、如何定义便于扩展？
3.  相同的返回对象，该如何根据不同的接口，返回不同的数据呢？
    
    > 比如，用户信息，列表查询的时候，只返回用户的姓名、年龄；响应查询的时候，需要返回用户的密码、创建时间等信息;
    > 
    > 而这些返回都是基于用户响应的DTO对象进行返回的；那如何能让其在不同的接口中返回不同的属性呢？

##### 响应格式规范 #####

*  方式一
    
    基于内置的标准状态码进行响应，不做任何新的错误码定义，异常、错误就直接响应对应的HttpStatus；正常就返回200并在body中带上业务数据；
    
     *  优点
        
        基于标准的状态码；不用进行新的定义；
        
        减少前后端对于状态码的沟通
     *  缺点
        
        标准的只是定义了一些最基本的，无法满足一些个性化的业务场景；不过这种场景，也可以基于响应数据的格式去做
 *  方式二
    
    不用内置的标准状态码，所有的接口请求不管是正常、异常、错误；全部返回200；然后在doby的数据中定义自己系统的状态码；客户端收到body的数据之后，根据前后端约定的状态码进行校验并友好提示；
    
     *  优点
        
        灵活性强；可以根据自己的业务场景，去定义个性化的规则，
        
        可扩展性强；可以根据需要任意扩展；
     *  缺点
        
        规则约定带来的负担，
        
        维护成本增加；可能因为定义不规范导致后续维护的困难；

上面说的方式，没有对错，只有合不合适，更多的是根据业务的需要，场景的需要，找更合适的方式；

下面采用了上面两种方式的二合一版本；去定义一套响应规范；

成功：

{ 
        "status": 200,
        "msg": "成功!",
        "data": { 
            "userName": "李四",
            "email": "lisi@qq.com"
        }
    }

失败：

{ 
        "status": 1000,
        "msg": "参数错误!"
    }

*  status
    
    当前请求的状态码；这里定义的是200为成功；200之外的为异常情况；
 *  msg
    
    状态码对应的描述
 *  data
    
    响应的数据；该属性是一个泛型值；其类型、值都是根据具体的业务场景需要进行匹配

##### 纯枚举的错误码定义（不采取） #####

> 我们可以延用系统自带的状态码；即org.springframework.http.HttpStatus枚举；但是这个往往只表述的一些通用的状态，不能够表达或说明一些详细的问题点；因此通常情况下我们会对错误码进行自定义；以更加详细的描述出现的问题；如下：

@Getter
    @AllArgsConstructor
    public enum BaseStatusCode { 
        SUCCESS(200,"成功!"),
    
        ERR_1000(1000,"参数错误!"),
    
        ERR_9999(9999,"未知错误!")
        ;
        // 状态码
        private Integer status;
    
        // 状态码描述
        private String msg;
    }

通常情况下就是这样去定义，使用也没有什么问题；但是这样写有一个比较大的问题；就是`不够灵活、不易于扩展`；因为这样，意味着所有的错误码都得定义在这一个枚举里面（后面的异常对象需要通过这个枚举值实例化）；比如说，用户模块、设备模块、电商模块、库存模块都有自己个性化的错误码；就意味着，所有的验证码都堆在这么一个注解里面；耦合性太强，不便于扩展；

##### 可扩展性状态码 #####

> 为了解决上面不灵活的问题，那我们就采用一种`面向接口`的状态码定义；来提高状态码的可扩展性和灵活性；
> 
> 调整起来也很简单，状态码同样也是以上面的枚举当时定义，但是`增加一个接口出来`；

*  第一步；**定义接口**
    
    > 该接口的
    
        /** * 错误码的接口 */
        public interface IStatusCode { 
            /** * 获取状态码 * @return 返回 */
             Integer getStatus();
        
            /** * 获取状态描述 * @return 返回描述信息 */
             String getMsg();
        }
 *  第二步；**定义状态码**
    
    > 此时；枚举中status和msg对应的get方法也就对应成了IStatusCode的实现
    
        @Getter
        @AllArgsConstructor
        public enum BaseStatusCode implements IStatusCode { 
            SUCCESS(200,"成功!"),
        
            ERR_1000(1000,"参数错误!"),
        
            ERR_9999(9999,"未知错误!")
            // 状态码
            private Integer status;
        
            // 状态码描述
            private String msg;
        }
 *  第三步；**扩展错误码**
    
        /** * @author LENOVO * @title: UserStatusCode * @projectName springcloud-mbb * @description: TODO 用户相关的状态码 * @date 2020/12/2 23:30 */
        @Getter
        @AllArgsConstructor
        public enum UserStatusCode implements IStatusCode{ 
            ERR_2000(2000,"用户信息不存在"),
        
            ERR_2001(2001,"用户昵称格式错误")
            ;
            // 状态码
            private Integer status;
        
            // 状态码描述
            private String msg;
        }
    
        /** * @author LENOVO * @title: DeviceStatusCode * @projectName springcloud-mbb * @description: TODO 设备相关的状态码 * @date 2020/12/2 23:33 */
        @Getter
        @AllArgsConstructor
        public enum DeviceStatusCode implements IStatusCode{ 
            ERR_3000(3000,"设备id有误"),
            ERR_3001(3001,"设备名称格式错误"),
            ERR_3002(3002,"设备MAC地址无效")
            ;
            // 状态码
            private Integer status;
        
            // 状态码描述
            private String msg;
        }
 *  第四步；状态码的获取
    
        IStatusCode baseStatusCode = BaseStatusCode.ERR_9999;
        IStatusCode userStatusCode = UserStatusCode.ERR_2000;
        IStatusCode deviceStatusCode = DeviceStatusCode.ERR_3002;
    
    如此获取，优势就展现出来了，不管是以枚举的状态码还是对象的方式，只要是`实现了IStatusCode接口的类`，都可以作为一个状态码对象；通过接口的getStatus()和getMsg()即可拿到状态码和状态描述；
    
    这样，我们就可以只需要把所有模块公共的状态码定义在公共模块里面；其他模块个性化的状态码，定义在模块内部即可；
 *  优点分析
    
     *  **定义解耦**；不需要将所有的状态码定义到一起了；`只要实现了IStatusCode接口即可`
     *  **不限于枚举**；因为是基于接口获取状态码和描述，因此不限于枚举，任何只要实现了IStatusCode都可以作为状态码

##### 公共响应对象定义 #####

有了规范好的响应对象的格式；有了状态码；那就可以定义一个基础的响应对象用来包装最后的返回结果；其中定义了4个构造方法，用于能够快速的实例化一个响应对象；

为了能更好的兼容；这里将HttpStatus状态码也封装了进来，这样就既可以使用默认状态码，可以使用自定义状态码，根据自己的需要灵活选择。

> 其中@JsonView的可以先不看，后面会介绍；只是为了后面不重复贴这一块的代码，先全部贴出来

/** * 基础的响应对象 * * @param <T> 响应数据 */
    @Data
    public class BaseResponceDto<T> { 
        /** * 响应数据最外层的视图 也是所有响应视图的父类 */
        public interface ResponceBaseDtoView { 
        }
    
        /** * 状态码 */
        @JsonView(ResponceBaseDtoView.class)
        private Integer status;
    
        /** * 状态描述 */
        @JsonView(ResponceBaseDtoView.class)
        private String msg;
    
        /** * 响应数据 */
        @JsonView(ResponceBaseDtoView.class)
        private T data;
    
        /** * 只有状态码的响应 * * @param statusCode */
        public BaseResponceDto(IStatusCode statusCode) { 
            if (null != statusCode) { 
                this.status = statusCode.getStatus();
                this.msg = statusCode.getMsg();
            }
        }
    
        /** * 有状态码且有参数的响应 * * @param statusCode * @param data */
        public BaseResponceDto(IStatusCode statusCode, T data) { 
            if (null != statusCode) { 
                this.status = statusCode.getStatus();
                this.msg = statusCode.getMsg();
            }
            if (null != data) { 
                this.data = data;
            }
        }
    
        /** * 根据HttpStatus响应 * * @param httpStatus http请求状态码 */
        public BaseResponceDto(HttpStatus httpStatus) { 
            if (null != httpStatus) { 
                this.status = httpStatus.value();
                this.msg = httpStatus.getReasonPhrase();
            }
        }
    
        /** * 根据http状态码返回 并返回额外返回数据 * * @param httpStatus http状态码 * @param data 数据 */
        public BaseResponceDto(HttpStatus httpStatus, T data) { 
            if (null != httpStatus) { 
                this.status = httpStatus.value();
                this.msg = httpStatus.getReasonPhrase();
            }
            if (null != data) { 
                this.data = data;
            }
        }
    
        /** * 根据异常响应错误码 * * @param baseException 异常对象 */
        public BaseResponceDto(BaseException baseException) { 
            if (null != baseException) { 
                this.status = baseException.getError();
                this.msg = baseException.getMsg();
                this.data = (T) baseException.getData();
            }
        }
    }

##### 响应数据初始化工具 #####

上面是提供了各种方式的构造方法，可以根据实际的需要进行实例化；为了能够更加方便的使用，所以这里写了一个静态工具类；用于将实例化响应对象的动作进一步封装，`让响应数据对象的实例化更加简单、便捷`；

/** * 响应帮助类 */
    public class ReturnUtils { 
    
        /** * 响应成功 * * @return */
        public static BaseResponceDto<Void> success() { 
            return new BaseResponceDto(BaseStatusCode.SUCCESS);
        }
    
        /** * 根据Http状态码返回 * * @return 基础的响应对象 */
        public static BaseResponceDto<Void> successByHttpStatus() { 
            return new BaseResponceDto(HttpStatus.OK);
        }
    
        /** * 根据自定义的状态码返回 * 有响应数据的成功 * * @param data 响应的数据 * @param <T> 响应的数据类型 * @return 基础的响应对象 */
        public static <T> BaseResponceDto success(T data) { 
            return new BaseResponceDto<T>(BaseStatusCode.SUCCESS, data);
        }
    
        /** * 根据http状态码返回 * * @param data 响应的数据 * @param <T> 响应的数据类型 * @return 基础的响应对象 */
        public static <T> BaseResponceDto successByHttpStatus(T data) { 
            return new BaseResponceDto<T>(HttpStatus.OK, data);
        }
    
        /** * 没有响应数据的失败 * * @param statusCode 状态码 * @return */
        public static BaseResponceDto<Void> error(BaseStatusCode statusCode) { 
            return new BaseResponceDto(statusCode);
        }
    
        /** * 有响应数据的失败 * * @param statusCode 状态码 * @param data 数据 * @return */
        public static <T> BaseResponceDto error(BaseStatusCode statusCode, T data) { 
            return new BaseResponceDto<T>(statusCode, data);
        }
    
        /** * 异常后的响应 * * @param baseException 异常 * @return */
        public static BaseResponceDto error(BaseException baseException) { 
            return new BaseResponceDto(baseException);
        }
    }

*  使用示例
    
    成功响应
    
        // 不带数据
        return ReturnUtils.success();
        // 带数据
        return ReturnUtils.success("123456");
    
    失败响应
    
        // 不带数据
        return ReturnUtils.error(BaseStatusCode.ERR_9999);
        
        // 带数据
        return ReturnUtils.error(BaseStatusCode.ERR_9999,"123456");

##### 使用JsonView；规范响应对象 #####

这个放在响应的最后说，是因为他并不属于响应结构的东西，但是他又属于响应的一部分，而且很重要；一个系统，权限是不可缺少的一部分，所谓的权限，简单的说，也就是不同的人，不同的接口，看到的数据不一样；同样是用户查询，用户列表只需要返回用户名即可，而用户详情就需要返回更多的数据；那么这种情况我们需要怎么去响应呢？定义多个响应DTO，当然这是最简单的方式；同样，我们也可以和validator中的分组一样；使用JsonView对响应的结果进行分组，使得同一个对象，在不同接口中返回不同的属性；

*  JsonView说明
    
    JsonView的定义和validator中的group是类似的概念；也是`基于接口`，使用也和validator类似；
 *  使用
    
     *  定义顶级接口
        
        > 此接口为所有JsonView接口的父类；其作用于响应的基础属性上；如下：
        
            @Data
            public class BaseResponceDto<T> { 
                /** * 响应数据最外层的视图 也是所有响应视图的父类 */
                public interface ResponceBaseDtoView { 
                }
                
                /** * 状态码 */
                @JsonView(ResponceBaseDtoView.class)
                private Integer status;
                
                //....
            }
     *  业务接口定义
        
        > 如下所示：
        > 
        > 所有视图都直接或者间接继承自ResponceBaseDtoView基础视图；否则会导致响应的BaseResponceDto对象为空json \{\}
        > 
        > 简单视图只返回用户名和手机号码
        > 
        > 详情视图，返回所有的属性
        
            /** * 用户响应请求 */
            @Data
            public class UserResponceDto { 
                // 简单视图，只返回最基数的属性
                public interface UserResponceSimpleDtoView extends BaseResponceDto.ResponceBaseDtoView { };
            
                // 详情视图，返回详细的属性参数
                public interface UserResponceDetailDtoView extends UserResponceSimpleDtoView { };
            
            
                /** * 用户名 */
                @JsonView(UserResponceSimpleDtoView.class)
                public String userName;
            
                /** * 年龄 */
                @JsonView(UserResponceDetailDtoView.class)
                private Integer age;
            
                /** * 性别 */
                @JsonView(UserResponceDetailDtoView.class)
                private Integer gender;
            
                /** * 邮箱 */
                @JsonView(UserResponceDetailDtoView.class)
                private String email;
            
                /** * 电话号码 */
                @JsonView(UserResponceSimpleDtoView.class)
                private String phoneNum;
            
                /** * 修改人 */
                @JsonView(UserResponceDetailDtoView.class)
                private String optUser;
            }
     *  使用；Controller指定视图
        
            @GetMapping("getSimple")
            // 指定JsonView的简单视图
            @JsonView(UserResponceDto.UserResponceSimpleDtoView.class)
            public BaseResponceDto getSimple() { 
                UserResponceDto userResponceDto = new UserResponceDto();
                userResponceDto.setUserName("张三");
                userResponceDto.setAge(10);
                userResponceDto.setEmail("zhangsan@qq.com");
                userResponceDto.setGender(0);
                userResponceDto.setPhoneNum("13888888888");
                userResponceDto.setOptUser("admin");
            
                return ReturnUtils.success(userResponceDto);
            }
            
            @GetMapping("getDetail")
            // 指定详细视图
            @JsonView(UserResponceDto.UserResponceDetailDtoView.class)
            public BaseResponceDto getDetail() { 
                UserResponceDto userResponceDto = new UserResponceDto();
                // 内容和上面一样
            
                return ReturnUtils.success(userResponceDto);
            }
        
        ![image-20201207000639957][]
        
        即可看到，两个接口，根据我们的指定，返回了不同的属性值。

##### 如何统一返回包装对象 #####

*  需求
    
    上面定义的代码；为了保证数据的响应格式是BaseResponceDto格式的；因此Controller所有的方法都是返回了这个对象；目的也是为了保证响应格式的一致性；但是，我国我们不返回这个对象可以吗？完全是可以的，而且也不会有任何报错；但是，这样却打破了我们定义的规则，导致响应的结构不一致了。
    
    能够在一个统一的地方去配置返回；保证响应的都是BaseResponceDto；而controller只需要返回数据即可；如下：
    
        @GetMapping("getSimple")
        @JsonView(UserResponceDto.UserResponceSimpleDtoView.class)
        public UserResponceDto getSimple() { 
            UserResponceDto userResponceDto = new UserResponceDto();
            // ....
            return userResponceDto;
        }
    
    响应自动包装外层结构
    
        { 
            "status": 200,
            "msg": "成功!",
            "data": { 
                "userName": "张三",
                "phoneNum": "13888888888"
            }
        }
 *  RestControllerAdvice拦截并重构响应
    
     *  创建继承自@ResponseBody的注解
        
        > 用来添加到方法或者类上；当响应写入body之间拦截结果
        
            /** * @author LENOVO * @title: ResponseDataBody * @projectName springcloud-mbb * @description: TODO 规范响应数据的注解 * @date 2020/12/1 15:24 */
            @Retention(RetentionPolicy.RUNTIME)
            @Target({ ElementType.TYPE, ElementType.METHOD})
            @Documented
            @ResponseBody
            public @interface ResponseDataBody { 
            }
     *  定义ResponseDataBodyAdvice拦截添加了@ResponseDataBody注解的响应
        
            @RestControllerAdvice(basePackages = "com.lupf")
            @Slf4j
            public class ResponseDataBodyAdvice implements ResponseBodyAdvice<Object> { 
            
                /** * 得到自定义的注解 */
                private static final Class<? extends Annotation> ANNOTATION_TYPE = ResponseDataBody.class;
            
                /** * 判断类或者方法是否使用了 @ResponseDataBody * 这里将注解添加在BaseController上面；以为着只要继承了BaseController的Controller都使用了该注解 */
                @Override
                public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) { 
                    return AnnotatedElementUtils.hasAnnotation(returnType.getContainingClass(), ANNOTATION_TYPE) || returnType.hasMethodAnnotation(ANNOTATION_TYPE);
                }
            
                /** * 当类或者方法使用了 @ResponseDataBody 也就是上面的方法返回的true 就会调用这个方法 */
                @Override
                public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) { 
                    // 防止重复包裹的问题出现 如果已经是要返回的基础对象了 就直接返回
                    if (body instanceof BaseResponceDto) { 
                        return body;
                    }
                    // 否则的话就直接返回
                    return ReturnUtils.success(body);
                }
            }
        
         *  supports
            
            判断是否指定了特定的注解
         *  beforeBodyWrite
            
            在写入body之前，会调用这个方法；因此，就可以在这里将响应对象给改掉
            
                if (body instanceof BaseResponceDto) { 
                    return body;
                }
                // 否则的话就直接返回
                return ReturnUtils.success(body);
         *  @RestControllerAdvice(basePackages = “com.lupf”)
            
            如果以jar的方式加入；这里务必要指明一下当前类所处的路径；否则可能因为没有扫描到导致加载失败。
 *  封装的优点
    
     *  规范响应；
        
        避免因为代码错误或者响应错误导致报文格式异常；这样写，可以包装返回的对象必定是BaseResponceDto
     *  减少冗余代码
        
        Controller中直接返回数据对象；封装统一去进行。

--------------------

#### 异常 ####

最后咱来说这个异常；在整个业务的请求到响应，异常并不是必定会出现的；但是，异常并不是必定会出现，但是又是不得不处理的；并且他贯穿了整个业务的始终，从请求到响应，都有可能牵扯到异常；所以一个好的异常处理机制，是整个代码健壮性必定要考虑的因素。

##### 定义业务异常 #####

*  为什么要定义业务异常
    
    上面，我们定义了各种异常码；目的也就是当代码不是按我们预想的方式在跑的话，就基于错误码，抛出异常，终止业务流程；但是现有的系统异常并不认我们的状态码；所以，我们需要自定义一个认识我们状态码的异常；
 *  异常定义
    
        /** * 基础异常 */
        @Data
        public class BaseException extends RuntimeException { 
        
            /** * 错误码 */
            private Integer error;
        
            /** * 错误描述 */
            private String msg;
        
            /** * 错误后响应的信息 */
            private Object data;
        
            /** * 根据错误码实例化异常 * * @param statusCode 自定义错误码 */
            public BaseException(IStatusCode statusCode) { 
                // 校验是否传递了异常码
                if (null == statusCode) { 
                    // 如果没有统一设置为未知错误
                    setInfo(BaseStatusCode.ERR_9999);
                } else { 
                    setInfo(statusCode);
                }
            }
        
            /** * 根据http状态码抛出异常 * * @param httpStatus http状态码 */
            public BaseException(HttpStatus httpStatus) { 
                if (null == httpStatus) { 
                    // 没有传递默认使用 未知异常
                    setInfo(BaseStatusCode.ERR_9999);
                } else { 
                    setInfo(httpStatus);
                }
            }
        
            /** * 根据错误码实例化异常 并返回数据 * * @param statusCode 自定义错误码 * @param data 数据 */
            public BaseException(IStatusCode statusCode, Object data) { 
                // 校验是否传递了异常码
                if (null == statusCode) { 
                    // 如果没有统一设置为未知错误
                    setInfo(BaseStatusCode.ERR_9999);
                } else { 
                    setInfo(statusCode);
                }
                // 校验数据是否为null
                if (null != data) { 
                    this.data = data;
                }
            }
        
            /** * 根据http的状态码实例化异常 并返回数据 * * @param httpStatus http状态码 * @param data 数据 */
            public BaseException(HttpStatus httpStatus, Object data) { 
                // 校验是否传递了异常码
                if (null == httpStatus) { 
                    // 如果没有统一设置为未知错误
                    setInfo(BaseStatusCode.ERR_9999);
                } else { 
                    setInfo(httpStatus);
                }
                // 校验数据是否为null
                if (null != data) { 
                    this.data = data;
                }
            }
        
        
            /** * 设置状态码及描述信息 * 内部使用的方法 * * @param statusCode */
            private void setInfo(IStatusCode statusCode) { 
                if (null != statusCode) { 
                    this.error = statusCode.getStatus();
                    this.msg = statusCode.getMsg();
                }
            }
        
            /** * 根据HttpStatus设置属性 * @param httpStatus */
            private void setInfo(HttpStatus httpStatus) { 
                if (null != httpStatus) { 
                    this.error = httpStatus.value();
                    this.msg = httpStatus.getReasonPhrase();
                }
            }
        }
    
     *  error
        
        错误码
     *  msg
        
        错误描述
     *  data
        
        绑定的数据，异常也可能需要返回数据，因此可以在这里去指定
     *  构造方法
        
        基于`IStatusCode`和`HttpStatus`的构造方法；用于快速实例化异常对象
 *  扩展异常
    
    如果因业务需要，在特定场所需要一些一些特殊的异常；我们可以再建BaseException的子类去进一步细化。
 *  抛异常
    
    > 异常定义好之后，想抛一个异常，自然就是很简单的啦
    
        throw new BaseException(HttpStatus.ACCEPTED, "123456");

##### 如何优雅的全局捕获异常 #####

*  问题点
    
    当我们的业务逻辑中出现了异常；比如要修改某个用户，请求的数据也没有问题；结果在修改直接去查找用户的时候，发现已经没有这个用户了；那么一般就抛出一个用户不存在的异常，如果不对异常进行处理的话，前端就只会收到一个400的错误；而我们希望的是这样：
    
        { 
            "status": 2001,
            "msg": "用户不存在!"
        }
 *  通过ExceptionHandler捕获全局异常
    
    > 定义一个BaseController；所有的controller都继承自他
    > 
    > 如下所示；当出现指定的异常之后；根据匹配，返回不同的响应数据；
    
        /** * Controller的的基础对象 * 所有的Controller都将继承自他 */
        @Slf4j
        @ResponseDataBody
        public class BaseController { 
        
            @ExceptionHandler(HttpMessageNotReadableException.class)
            @ResponseStatus(HttpStatus.BAD_REQUEST)
            @ResponseBody
            public Object HttpMessageNotReadableExceptionHandler(HttpMessageNotReadableException httpMessageNotReadableException){ 
                log.error("捕获请求参数读取异常....",httpMessageNotReadableException);
                // 前端未传递参数 导致读取参数异常
                return ReturnUtils.error(BaseStatusCode.ERR_1000);
            }
        
            @ExceptionHandler(BindException.class)
            @ResponseStatus(HttpStatus.BAD_REQUEST)
            @ResponseBody
            public Object bindExceptionHandler(BindException bindException){ 
                log.error("捕获请求参数校验异常....",bindException);
                // 获取到所有的校验失败的属性
                List<FieldError> fieldErrors = bindException.getFieldErrors();
        
                // 实例化一个用于装参数错误的list
                List<ParamErrDto> paramErrDtos = new ArrayList<>();
                for (FieldError fieldError : fieldErrors) { 
                    // 那段字段名
                    String field = fieldError.getField();
                    // 拿到异常的描述
                    String defaultMessage = fieldError.getDefaultMessage();
                    log.info("field:{} msg:{}", field, defaultMessage);
                    // 添加到list中去
                    paramErrDtos.add(new ParamErrDto(field, defaultMessage));
                }
        
                // 返回前端参数错误 并告诉前端那些字段不对 具体描述是什么
                return ReturnUtils.error(BaseStatusCode.ERR_1000, paramErrDtos);
            }
        
            @ExceptionHandler(BaseException.class)
            @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
            @ResponseBody
            public Object baseExceptionHandler(BaseException baseException){ 
                log.error("捕获到业务异常!",baseException);
                // 基础的业务异常
                return ReturnUtils.error(baseException);
            }
        
            /** * 通过ExceptionHandler 捕获controller未捕获到的异常，给用户一个友好的返回 * * @param ex 异常信息 * @return */
            @ExceptionHandler(Exception.class)
            @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
            @ResponseBody
            public Object exceptionHandler(Exception ex) { 
                log.error("exceptionHandler....");
                // 所有的 自定义的、已知的异常全部都没有匹配上
                // 直接响应响应一个未知错误的提醒
                return ReturnUtils.error(BaseStatusCode.ERR_9999);
            }
        }
    
    使用
    
        public class UserController extends BaseController { 
        // ....
        }
    
     *  @ExceptionHandler(HttpMessageNotReadableException.class)
        
        当body没有传参数时，会触发这个异常，并返回参数错误的状态码
     *  @ExceptionHandler(BindException.class)
        
        当validator校验失败之后，会触发这个异常；因此这里将所有不符合规范的传参整理成列表返回。
     *  @ExceptionHandler(BaseException.class)
        
        自定义业务异常；直接将异常对象转换为响应对象；返回给前端
     *  @ExceptionHandler(Exception.class)
        
        用来处理那些没有特定处理的异常；然后由这里拦截之后，统一返回未知错误；

#### 总结 ####

请求、响应、异常是每项业务不可或缺的一部分；三者相辅相成，缺一不可，所谓的规范，也就是让他们三个之间衔接、配合的更顺畅、更默契；因此，只有一开始就将一系列的东西考虑清楚并打好地基，才会使得后面的路越走越顺；

--------------------

扫码关注公众号，回复【**资料**】获取更多最新的学习、面试资料。![在这里插入图片描述][07290db2ca31e0d8afdf22adf8f3da0f.png_pic_center]

[image-20201207014448887]: /images/20221120/107a76a44fb441ad8a6290912eeeb548.png
[hibernate-validator]: https://mvnrepository.com/artifact/org.hibernate.validator/hibernate-validator
[image-20201201231837804]: /images/20221120/5274cc8add954a87a6f81465a584607f.png
[image-20201201233848289]: /images/20221120/53d287bc64da4a24a51299e3fe95441a.png
[image-20201202230819477]: /images/20221120/a28d1253367f45d98ea49096df4d5e4e.png
[image-20201207000639957]: /images/20221120/27dd126bd225424d84552167cb0ff4d2.png
[07290db2ca31e0d8afdf22adf8f3da0f.png_pic_center]: /images/20221120/730c976cc3174139854cfe74d6834558.png