--- theme: hydrogen --- ## 前言参数校验这个东西，很多情况下都是比较简单的，用 `@NotNull`、`@Size` 等注解就可以解决绝大多数场景，但也有一些场景是这些基本注解解决不了的，只能用一些其他的方式处理，这样就导致参数校验变成了多层，其实是不利于代码维护的。于是乎，我写了一套几乎可以满足任何场景的参数校验组件，非常好用，安利给大家。 > GitHub：[stick-i/spel-validator: 一个强大的 Java 参数校验包，基于 SpEL 实现，扩展自 javax.validation 包，几乎支持所有场景下的参数校验。 (github.com)](https://github.com/stick-i/spel-validator) ## 💡 它解决了什么问题？ * 枚举值字段校验： ```java @SpelAssert(assertTrue = " T(cn.sticki.enums.UserStatusEnum).getByCode(#this.userStatus) != null ", message = "用户状态不合法") private Integer userStatus; ``` * 多字段联合校验： ```java @NotNull private Integer contentType; @SpelNotNull(condition = "#this.contentType == 1", message = "语音内容不能为空") private Object audioContent; @SpelNotNull(condition = "#this.contentType == 2", message = "视频内容不能为空") private Object videoContent; ``` * 复杂逻辑校验，调用静态方法： ```java // 中文算两个字符，英文算一个字符，要求总长度不超过 10 // 调用外部静态方法进行校验 @SpelAssert(assertTrue = "T(cn.sticki.util.StringUtil).getLength(#this.userName) <= 10", message = "用户名长度不能超过10") private String userName; ``` * 调用 Spring Bean（需要使用 @EnableSpelValidatorBeanRegistrar 开启Spring Bean支持）： ```java // 这里只是简单举例，实际开发中不建议这样判断用户是否存在 @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.0.2-beta ```xml cn.sticki spel-validator Latest Version org.hibernate.validator hibernate-validator ${hibernate-validator.version} org.springframework.boot spring-boot-starter-web ${spring-boot-starter-web.version} ``` * 在接口参数上使用 `@Valid` 或 `@Validated` 注解 ```java @RestController @RequestMapping("/example") public class ExampleController { /** * 简单校验示例 */ @PostMapping("/simple") public Resp simple(@RequestBody @Valid SimpleExampleParamVo simpleExampleParamVo) { return Resp.ok(null); } } ``` * 在实体类上使用 `@SpelValid` 注解，同时在需要校验的字段上使用 `@SpelNotNull` 等约束注解 ```java @Data @SpelValid public class SimpleExampleParamVo { @NotNull private Boolean switchAudio; /** * 当 switchAudio 为 true 时，校验 audioContent，audioContent 不能为null */ @SpelNotNull(condition = "#this.switchAudio == true", message = "语音内容不能为空") private Object audioContent; } ``` * 添加全局异常处理器，处理校验异常 ```java @RestControllerAdvice public class ControllerExceptionAdvice { @ExceptionHandler({BindException.class, MethodArgumentNotValidException.class}) public Resp 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 校验不通过

* 请求体： ```json { "switchAudio": true, "audioContent": null } ``` * 响应体 ```json { "code": 400, "message": "audioContent 语音内容不能为空", "data": null } ```

示例二：校验通过

* 请求体 ```json { "switchAudio": false, "audioContent": null } ``` * 响应体 ```json { "code": 200, "message": "成功", "data": null } ```

示例三：@NotNull 校验不通过

* 请求体 ```json { "switchAudio": null, "audioContent": null } ``` * 响应体 ```json { "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 支持。 ```java @EnableSpelValidatorBeanRegistrar @SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } } ``` ### 自定义约束注解 1. 在注解上使用 `@SpelConstraint` ，并指定验证器。 2. 然后给注解添加上三个固定的字段 message 、group、condition。 3. 实现验证器 ![自定义示例约束示例-定义约束注解](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2aa3a5f0eb7d425b911867048e1c92b8~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1304\&h=1167\&s=194707\&e=png\&b=1e1f22) ![自定义约束示例-实现验证器](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/38ee982f6a4c423fbeb9ecd473436c23~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1367\&h=477\&s=57232\&e=png\&b=1f2023) 具体实现方式可以参考 `cn.sticki.validator.spel.SpelConstraint` 类。如果你使用过 `javax.validation` 的自定义约束注解，那么你会发现 `SpEL Validator` 的自定义约束注解几乎与 `javax.validation` 一致。 ## 📦 示例项目我也写了一个简单的示例项目，但目前还不太完善，只有基本的使用方法： * ## 最后 ### 关于性能性能上我目前还没有进行测试，但代码里使用了很多的反射，会有一定的损耗，后面我准备多加一些缓存，尽量降低性能上的影响。 ### 一个奇怪的现象在项目中使用SpEL的时候，有一个很怪异的现象： ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/64d15c294aba492ebcce199308ada330~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1647\&h=675\&s=102645\&e=png\&b=1e1f22) 我给这两个字段都标记了 `@Language("SpEL")`，但是只有 `condition` 可以识别，我不知道这算不算idea的bug，我目前使用的idea版本是 IntelliJ IDEA 2024.1 (Ultimate Edition)，有懂的朋友请帮忙解答一下。 ### 最后的最后贴一下GitHub地址：（顺手点个star呀\~）欢迎大家进行体验，有任何疑问欢迎一起讨论。 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/8c70aa806caa4cd8ba7e0d8161e225a4~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=205\&h=239\&s=535675\&e=gif\&f=13\&b=767a87)