🤯我写了一套几乎无敌的参数校验组件!

举报
阿杆 发表于 2024/11/04 09:41:48 2024/11/04
【摘要】 这是一个强大的 Java 参数校验包,基于 SpEL 实现,扩展自 javax.validation 包,几乎支持所有场景下的参数校验。

前言

大家好,我是阿杆,不是阿轩。

参数校验这个东西,很多情况下都是比较简单的,用 @NotNull@Size 等注解就可以解决绝大多数场景,但也有一些场景是这些基本注解解决不了的,只能用一些其他的方式处理,这样就导致参数校验变成了多层,其实是不利于代码维护的。

于是乎,我写了一套几乎可以满足任何场景的参数校验组件,非常好用,安利给大家。

GitHub:https://github.com/stick-i/spel-validator

image.png

💡 它解决了什么问题?

  • 枚举值字段校验:

    @SpelAssert(assertTrue = " T(cn.sticki.enums.UserStatusEnum).getByCode(#this.userStatus) != null ", message = "用户状态不合法")
    private Integer userStatus;
    
  • 多字段联合校验:

    @NotNull
    private Integer contentType;
    
    @SpelNotNull(condition = "#this.contentType == 1", message = "语音内容不能为空")
    private Object audioContent;
    
    @SpelNotNull(condition = "#this.contentType == 2", message = "视频内容不能为空")
    private Object videoContent;
    
  • 复杂逻辑校验,调用静态方法:

    // 中文算两个字符,英文算一个字符,要求总长度不超过 10
    // 调用外部静态方法进行校验
    @SpelAssert(assertTrue = "T(cn.sticki.util.StringUtil).getLength(#this.userName) <= 10", message = "用户名长度不能超过10")
    private String userName;
    
  • 调用 Spring Bean(需要使用 @EnableSpelValidatorBeanRegistrar 开启Spring Bean支持):

    // 这里只是简单举例,实际开发中不建议这样判断用户是否存在
    @SpelAssert(assertTrue = "@userService.getById(#this.userId) != null", message = "用户不存在")
    private Long userId;
    
  • 更多使用场景,欢迎探索和补充!

📝 特点

  • 强大的参数校验功能,几乎支持所有场景下的参数校验。
  • 扩展自 javax.validation 包,只新增不修改,无缝集成到项目中。
  • 基于 SpEL(Spring Expression Language) 表达式,支持复杂的校验逻辑。
  • 支持调用 Spring Bean,可在表达式中使用注入过的 Spring Bean。
  • 校验时基于整个对象,支持对象内字段间的校验逻辑。
  • 支持自定义校验注解,可根据业务需求自定义校验逻辑。
  • 无需额外的异常处理,校验失败时会上报到 javax.validation 的异常体系中。
  • 简单易用,使用方式几乎与 javax.validation 一致,学习成本低,上手快。

🎈 环境

目前仅测试了 JDK8 环境,理论上来说 JDK8+ 应该都是支持的。

📦 快速开始

  • 添加依赖

    Latest Version: 0.3.0-beta(文章发布时的最新版本)

    <dependency>
        <groupId>cn.sticki</groupId>
        <artifactId>spel-validator</artifactId>
        <version>Latest Version</version>
    </dependency>
    
    <dependency>
        <groupId>org.hibernate.validator</groupId>
        <artifactId>hibernate-validator</artifactId>
        <version>${hibernate-validator.version}</version>
    </dependency>
    
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>${spring-boot-starter-web.version}</version>
    </dependency>
    
  • 在接口参数上使用 @Valid@Validated 注解

    @RestController
    @RequestMapping("/example")
    public class ExampleController {
    
      /**
       * 简单校验示例
       */
      @PostMapping("/simple")
      public Resp<Void> simple(@RequestBody @Valid SimpleExampleParamVo simpleExampleParamVo) {
        return Resp.ok(null);
      }
    
    }
    
  • 在实体类上使用 @SpelValid 注解,同时在需要校验的字段上使用 @SpelNotNull 等约束注解

    @Data
    @SpelValid
    public class SimpleExampleParamVo {
    
      @NotNull
      private Boolean switchAudio;
    
      /**
       * 当 switchAudio 为 true 时,校验 audioContent,audioContent 不能为null
       */
      @SpelNotNull(condition = "#this.switchAudio == true", message = "语音内容不能为空")
      private Object audioContent;
    
    }
    
  • 添加全局异常处理器,处理校验异常

    @RestControllerAdvice
    public class ControllerExceptionAdvice {
    
      @ExceptionHandler({BindException.class, MethodArgumentNotValidException.class})
      public Resp<Void> handleBindException(BindException ex) {
        String msg = ex.getFieldErrors().stream()
            .map(error -> error.getField() + " " + error.getDefaultMessage())
            .reduce((s1, s2) -> s1 + "," + s2)
            .orElse("");
        return new Resp<>(400, msg);
      }
    
    }
    
  • 发起请求,即可看到校验结果

    • 示例一:@SpelNotNull 校验不通过

      请求体:

      {
        "switchAudio": true,
        "audioContent": null
      }
      

      响应体

      {
        "code": 400,
        "message": "audioContent 语音内容不能为空",
        "data": null
      }
      
    • 示例二:校验通过

      请求体

      {
        "switchAudio": false,
        "audioContent": null
      }
      

      响应体

      {
        "code": 200,
        "message": "成功",
        "data": null
      }
      
    • 示例三:@NotNull 校验不通过

      请求体

      {
        "switchAudio": null,
        "audioContent": null
      }
      

      响应体

      {
        "code": 400,
        "message": "switchAudio 不能为null",
        "data": null
      }
      

📖 使用指南

注意:本组件的目的不是代替 javax.validation 的校验注解,而是作为一个扩展,方便某些场景下的参数校验。能够使用 javax.validation 的场景就不要使用 spel-validator ,因为 spel-validator 会有一定的性能损耗。

开启约束校验

需要满足以下两个条件,才会对带注解的元素进行校验:

  1. 在接口参数上使用 @Valid@Validated 注解
  2. 在实体类上使用 @SpelValid 注解

如果只满足第一个条件,那么只会对带 @NotNull@NotEmpty@NotBlank 等注解的元素进行校验。

如果只满足第二个条件,那么不会对任何元素进行校验。

这是因为 @SpelValid 注解是基于 javax.validation.Constraint 实现的,只有在 @Valid@Validated 注解的支持下才会生效。
spel-validator 提供的约束注解是基于 @SpelValid 进行扫描校验的,只有在 @SpelValid 注解生效的情况下才会执行约束校验。

使用约束注解

目前支持的约束注解有:

注解 说明 对标 javax.validation
@SpelAssert 逻辑断言校验
@SpelNotNull 非 null 校验 @NotNull
@SpelNotEmpty 集合、字符串、数组大小非空校验 @NotEmpty
@SpelNotBlank 字符串非空串校验 @NotBlank
@SpelNull 必须为 null 校验 @Null
@SpelSize 集合、字符串、数组长度校验 @Size

每个约束注解都包含三个默认的属性:

  • message:校验失败时的提示信息。
  • group:分组条件,支持 SpEL 表达式,当分组条件满足时,才会对带注解的元素进行校验。
  • condition:约束开启条件,支持 SpEL 表达式,当 表达式为空 或 计算结果为true 时,才会对带注解的元素进行校验。

调用 Spring Bean

默认情况下,解析器无法识别 SpEL 表达式中的 Spring Bean。

如果需要在 SpEL 表达式中调用 Spring Bean,需要在启动类上添加 @EnableSpelValidatorBeanRegistrar 注解,
开启 Spring Bean 支持。


@EnableSpelValidatorBeanRegistrar
@SpringBootApplication
public class Application {

  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }

}

自定义约束注解

  1. 在注解上使用 @SpelConstraint ,并指定验证器。
  2. 然后给注解添加上三个固定的字段 message 、group、condition。
  3. 实现验证器

image.png

image.png

具体实现方式可以参考 cn.sticki.validator.spel.SpelConstraint 类。

如果你使用过 javax.validation 的自定义约束注解,那么你会发现 SpEL Validator 的自定义约束注解几乎与 javax.validation
一致。

📦 示例项目

我也写了一个简单的示例项目,但目前还不太完善,只有基本的使用方法:

最后

关于性能

在我的开发机上(Mac mini 2023款,M2芯片),经过了多组测试,得出如下结果:

在每个请求中,本组件校验参数所消耗的时间大约在1ms。

具体的测试说明,可以查看 https://spel-validator.sticki.cn/guide/FAQ.html#关于性能

最后的最后

贴一下GitHub地址:https://github.com/stick-i/spel-validator (顺手点个star呀~)

欢迎大家进行体验,有任何疑问欢迎一起讨论。

【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。