要想接口做的好、入参校验少不了!

要想接口做的好、入参校验少不了!

敲得码黛 1,450 2021-03-03

前言

两年前我刚步入社会接受毒打时,对整个开发流程还没什么概念,当时我以为的开发工作=“CRUD+接口对接”,所以代码写的那叫一个为所欲为(Map传参、不加注释、不打日志等等等等)。后来我被分到另一个项目组,原来的代码被我一个同事接手,后来这位同事辞职了。。。。。

老大瞅了一眼我写的代码,差点没把早上吃的两个包子吐出来,然后拉着我就是长达一个小时的谈话,啥代码可读性、接口可用性、系统健壮性啥的,咱也听不懂呀,从头到尾就听明白了一句话:“系统的Bug 80%以上都是因为没有做入参校验”。

小何内心ps:曾经有一个机会摆在我面前,我没有好好珍惜,如果上天再给我个机会,我一定会做好入参校验,如果非要给这件事情加个期限,我希望是Just Now

环境准备

假设我们现在需要编写一个下单接口,这个接口的参数包含商户订单号(orderId)、订单金额(money)、支付方式(payType)、平台商户号(pfMchId)、子商户号(subMchId)等字段,按照之前的写法,这个接口应该长如下模样

@RestController
public class OrderController {

 @PostMapping("/unifiedOrder")
 public String unifiedOrder(@RequestBody Map map){
     if (map.get("orderId") != null) {
         if (map.get("orderMoney") != null) {
             if (map.get("payType") != null) {
                 if(map.get("mchId") !=null&& map.get("subMchId")!=null){
                     // TO DO SOMETHING
                     return "SUCCESS";
                 }else{
                     return "平台商户号与子商户号不能同时为空";
                 }
             }else{
                 return "支付类型不能为空";
             }
         }else{
             return "订单金额不能为空";
         }
     }else{
         return "订单号不能为空";
     }

 }
}

看完这段代码不知道你怎么想,反正放到现在肯定是要被我DS的,下面就开始着手于此接口的改造。

Spring validation

引入依赖

如果是基于SpringBoot 2.3之前版本的项目会默认引入此依赖。2.3之后的版本则需要手动引入此依赖

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

创建数据模型

这一步其实是为了避免使用Map传递数据,毕竟Map的可读性实在是不怎么理想(觉得这一步没有必要的拉出去毒打一顿

于是将接口的入参模型Map改为如下数据模型

/**
 * 下单接口入参模型
 * @author hcq
 * @date 2021/3/13 13:23
 */
@Data
public class OrderModel {

    /**
     * 订单Id
     */
    private String orderId;

    /**
     * 订单金额
     */
    private String money;

    /**
     * 支付方式
     */
    private String payType;

    /**
     * 平台商户号
     */
    private String pfMchId;

    /**
     * 子商户号
     */
    private String subMchId;
}

接口变更如下

@RestController
public class OrderController {

    @PostMapping("/unifiedOrder")
    public String unifiedOrder(@RequestBody OrderModel order){
        if (order.getOrderId() != null) {
            if (order.getMoney() != null) {
                if (order.getPayType() != null) {
                    if(order.getPfMchId()!=null&& order.getSubMchId()!=null){
                        // TO DO SOMETHING
                        return "SUCCESS";
                    }else{
                        return "平台商户号与子商户号不能同时为空";
                    }
                }else{
                    return "支付类型不能为空";
                }
            }else{
                return "订单金额不能为空";
            }
        }else{
            return "订单号不能为空";
        }

    }
}

好吧~看起来几乎没啥变动,重头戏还在后面

SpringValidation(划重点了呃)

Spring的Validation组件使用起来十分简洁,只需要简单的两步

  • 在需要校验的接口参数前加上@Valid或者是@Validated 注解

    @RestController
    public class OrderController {
    
        @PostMapping("/unifiedOrder")
        public String unifiedOrder(@Validated @RequestBody OrderModel order) {
            if (order.getPfMchId() != null && order.getSubMchId() != null) {
                // TO DO SOMETHING
                return "SUCCESS";
            } else {
                return "平台商户号与子商户号不能同时为空";
            }
        }
    
    }
    
  • 在需要校验的字段上添加校验规则及提示信息

    @Data
    public class OrderModel {
    
        /**
         * 订单Id
         */
        @NotNull(message = "订单Id不能为空")
        private String orderId;
    
        /**
         * 订单金额
         */
        @NotNull(message = "订单金额不能为空")
        private String money;
    
        /**
         * 支付方式
         */
        @NotNull(message = "支付方式不能为空")
        private String payType;
    
        /**
         * 平台商户号
         */
        private String pfMchId;
    
        /**
         * 子商户号
         */
       private String subMchId;
    }    
    

做完这两步后,一个简单的入参校验就已经完成了。如果@NotNull修饰的字段为null值,那么后端服务器将会抛出BindException参数绑定异常,json类型入参则抛出MethodArgumentNotValidException异常,两种异常内部都包含着所有不符合规则的字段提示信息,此时可以由全局异常处理器捕获到此异常并进行异常响应(不清楚全局异常处理器怎样使用的可以参考我之前的文章)。

执行结果分析

PostMan发起请求,后端服务器抛出的MethodArgumentNotValidException异常被默认异常处理器DefaultHandlerExceptionResolver拦截,然后打印了相关异常信息

Validation常见的校验注解

  • @NotNull :该字段不允许为null值
  • @NotEmpty:该字段不允许为null值或空值,此注解同样适用于校验集合不允许为空
  • @Null:该注解与@NotNull正好相反,标识该字段必须为Null
  • @Pattern:通过正则表达式进行匹配,若该值无法匹配成功则抛出异常
  • @Max:通常使用在数字类型字段,标识该字段最大取值
  • @Min:通常使用在数字类型字段,标识该字段最小取值
  • @Lenth:标识该字段长度范围

自定义参数校验注解

我们会发现Validation提供的注解大多时候只能满足一些简单的校验场景,稍微复杂一点的场景就不适用于此规则了,例如最常见的一些接口规则有:多选一必填(Or)、只允许某些值中的一个(In)、多个字段不能同时上送(Mutex)等,这个时候我们可以通过自定义注解来完成相关参数的校验。还是拿刚才的栗子来讲,我们可以通过定义一个@Or自定义注解实现"pfMchId与subMchId二选一必填"的校验规则

接口改造如下

@PostMapping("/unifiedOrder")
public String unifiedOrder(@Validated @RequestBody OrderModel order) {
        // TO DO SOMETHING
        return "SUCCESS";
}

创建自定义注解Or

@Target({ElementType.TYPE})
@Repeatable(List.class)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = InVerifyHandler.class)
public @interface Or {

    String[] fields() default {};

    String message() default "Invalid ID!";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};

    
    @Target({ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @interface List{
        Or[] value();
    }

}
  • @Target({ElementType.TYPE}):标识该注解的作用域(作用Class上)

  • @Repeatable(List.class):标志该注解可以在同一对象上重复声明

  • @Retention(RetentionPolicy.RUNTIME):标识该注解的生命周期(保留至运行时)

  • @Constraint(validatedBy = InVerifyHandler.class):标识该注解的处理类

注解处理类

@Slf4j
public class InVerifyHandler implements ConstraintValidator<Or,Object> {

    private String[] fields;

    @Override
    public void initialize(Or targetAnno) {
        fields = targetAnno.fields();
    }

    @Override
    public boolean isValid(Object value, ConstraintValidatorContext context) {
        if(fields.length==0){
            return true;
        }
        try {
            for (String field : fields) {
                Field file = value.getClass().getDeclaredField(field);
                file.setAccessible(true);
                if(file.get(value)!=null){
                    return true;
                }
            }
        }catch (Exception e){
            log.error("自定义校验注解异常:",e);
        }
        return false;
    }
}

使用介绍

@Data
@Or(fields = {"pfMchId","subMchId"},message = "pfMchId、subMchId不能同时为空")
public class OrderModel {
    /**
     * 平台商户号
     */
    private String pfMchId;

    /**
     * 子商户号
     */
   private String subMchId;
}

通过Validation注解+自定义参数校验注解几乎可以覆盖绝大多数的校验场景,当然也不可能做到百分之百覆盖,一些业务场景上的校验还是有必要手动处理一下的。

本期文章就到这里啦,你学废了吗?


# spring # 全局参数校验