feat: 升级到v0.4.0 beta (#45)

Author: stick-i

.editorconfig

@@ -4,7 +4,7 @@ end_of_line = crlf
 indent_size = 4
 indent_style = space
 insert_final_newline = false
-max_line_length = 120
+max_line_length = 150
 tab_width = 4
 ij_continuation_indent_size = 8
 ij_formatter_off_tag = @formatter:off
@@ -35,7 +35,6 @@ ij_css_use_double_quotes = true
 ij_css_value_alignment = do_not_align
 
 [*.java]
-max_line_length = 150
 ij_smart_tabs = true
 ij_visual_guides = 100
 ij_java_align_consecutive_assignments = false

.github/workflows/deploy-docs.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches:
       # 确保这是你正在使用的分支名称
-      - docs
+      - main
   # 手动触发部署
   workflow_dispatch:
 

.github/workflows/mvn-test.yml

@@ -1,6 +1,15 @@
 name: run mvn test
 
-on: [ push, pull_request, workflow_dispatch ]
+on:
+  push:
+    branches:
+      - 'v*'
+  pull_request:
+    branches:
+      - 'v*'
+      - 'main'
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
 
 jobs:
   run-mvn-test:
@@ -11,12 +20,12 @@ jobs:
       - uses: actions/setup-java@v4
         with:
           distribution: 'zulu'
-          java-version: '8'
+          java-version: '11'
           cache: maven
 
       - run: |
           java -version
           mvn -v
 
       - run: mvn verify
-      - run: mvn clean test jacoco:report coveralls:report -DrepoToken="${{secrets.COVERALLS_TOKEN}}"
+      - run: mvn clean test coveralls:report -DrepoToken="${{secrets.COVERALLS_TOKEN}}" -f pom.xml

.run/jacoco_report.run.xml

@@ -13,15 +13,15 @@ actions:
 
 features:
   - title: 易上手
-    details: 设计直观，简单易用，与 javax.validation 使用方式高度相似，学习成本低，上手快。
+    details: 设计直观，简单易用，与 jakarta.validation-api 使用方式高度相似，学习成本低，上手快。
   - title: 极致灵活
     details: 利用 SpEL（Spring Expression Language）的强大功能，轻松实现复杂验证逻辑，且能够直接调用已注入的 Spring Beans 进行验证。
   - title: 无缝集成
-    details: 扩展自 javax.validation 包，只新增不修改，无缝集成到现有项目中。
+    details: 扩展自 jakarta.validation-api 包，只新增不修改，无缝集成到现有项目中。
   - title: 上下文感知
     details: 能够在整个对象的上下文中进行验证，支持跨字段的逻辑验证，提高数据完整性检查的效率和准确性。
   - title: 异常友好
-    details: 验证失败时自动整合进 javax.validation 的异常管理体系，简化错误处理流程。
+    details: 验证失败时自动整合进 jakarta.validation-api 的异常管理体系，简化错误处理流程。
   - title: 完全可定制
     details: 支持创建自定义约束注解，允许根据具体业务需求灵活定义验证规则。
 

document/web-docs/docs/README.md

@@ -59,3 +59,29 @@
 - 20线程，30循环，共9000次此请求，总耗时约为 1190ms，平均每个请求耗时约0.13ms，其中解析SpEL表达式的总耗时为 390ms，占比约33%。
 
 这样看来，目前的性能表现还算可以接受，但还有优化空间，后续会继续优化。
+
+## 如何对实体类单独进行校验
+
+正常情况下，只需要触发 jakarta.validation-api 的校验，就会顺带触发 spel.validator 的校验。
+这一点可以参考下源码的测试工具`cn.sticki.spel.validator.jakarta.JakartaSpelValidator.validate`的实现，大概是下面这个样子：
+
+```java
+    private static final Validator validator = Validation.byDefaultProvider()
+        .configure()
+        .messageInterpolator(new ParameterMessageInterpolator())
+        .buildValidatorFactory().getValidator();
+
+    /**
+     * 参数校验
+     * <p>
+     * 调用此方法会触发 jakarta.validation.constraints.* 的校验，类似于使用 @Valid 注解
+     *
+     * @return 校验结果，如果校验通过则返回空列表
+     */
+    public static <T> Set<ConstraintViolation<T>> validate(T obj) {
+        return validator.validate(obj);
+    }
+```
+
+如果你的实体类中只有 spel.validator 的校验注解，或者你只想触发 spel.validator 的校验，
+那更简单，你只需要调用 `cn.sticki.spel.validator.core.SpelValidExecutor#validateObject` 即可触发校验。

document/web-docs/docs/guide/FAQ.md

@@ -1,7 +1,7 @@
 # 自定义约束注解
 
 ::: tip
-如果你使用过 `javax.validation` 的自定义约束注解，那么你会发现 `SpEL Validator` 的自定义约束注解几乎与 `javax.validation` 一致。
+如果你使用过 `jakarta.validation-api` 的自定义约束注解，那么你会发现 `SpEL Validator` 的自定义约束注解几乎与 `jakarta.validation-api` 一致。
 :::
 
 下面以 `@SpelNotBlank` 为例，展示如何实现自定义约束注解。

document/web-docs/docs/guide/custom.md

@@ -1,14 +1,12 @@
 # 介绍
 
-SpEL Validator 是基于 Spring Expression Language 的参数校验包，也是 javax.validation 的扩展增强包，用于简化参数校验，它几乎支持所有场景下的参数校验。
+SpEL Validator 是基于 Spring Expression Language 的参数校验包，也是 jakarta.validation-api 的扩展增强包，用于简化参数校验，它几乎支持所有场景下的参数校验。
 
 设计的初衷是为了解决一些需要判断另一个字段的值来决定当前字段是否校验的场景。
 
 ::: tip
 
-本组件的目的不是代替 `javax.validation` 的校验注解，而是作为一个扩展，方便某些场景下的参数校验。
-
-原则上来说，能够使用 `javax.validation` 处理的场景就不应该使用 `spel-validator` 。
+本组件的目的不是代替 `jakarta.validation-api` 的校验注解，而是作为一个扩展，方便某些场景下的参数校验。
 
 :::
 

document/web-docs/docs/guide/introduction.md

@@ -2,36 +2,36 @@
 
 ::: warning
 
-本组件的目的不是代替 `javax.validation` 的校验注解，而是作为一个扩展，方便某些场景下的参数校验。
+本组件的目的不是代替 `jakarta.validation-api` 的校验注解，而是作为一个扩展，方便某些场景下的参数校验。
 
-原则上来说，能够使用 `javax.validation` 处理的场景就不应该使用 `spel-validator` 。
+原则上来说，能够使用 `jakarta.validation-api` 处理的场景就不应该使用 `spel-validator` 。
 
 :::
 
 ## 支持的版本
 
-- JDK8+
+| 组件                       | JDK | SpringBoot |
+|--------------------------|-----|------------|
+| spel-validator-core      | 8+  | 2.x, 3.x   |
+| spel-validator-constrain | 8+  | 2.x, 3.x   |
+| spel-validator-javax     | 8+  | 2.x        |
+| spel-validator-jakarta   | 11+ | 3.x        |
+
+一般情况下，您只需要考虑使用 `-javax` 或 `-jakarta` 这两个版本即可。
 
 ## 添加依赖
 
 Latest Version:
 [![Maven Central](https://img.shields.io/maven-central/v/cn.sticki/spel-validator.svg)](https://central.sonatype.com/search?q=g:cn.sticki%20a:spel-validator)
 
-大多数情况下，你只需要添加以下两个依赖：
+根据项目的实际情况，引入 `spel-validator-javax` 或 `spel-validator-jakarta` ：
 
 ```xml
 <dependencys>
   <dependency>
     <groupId>cn.sticki</groupId>
-    <artifactId>spel-validator</artifactId>
-    <version>Latest Version</version>
-  </dependency>
-
-  <!-- 基于 javax.validation 标准的校验器实现类 -->
-  <dependency>
-    <groupId>org.hibernate.validator</groupId>
-    <artifactId>hibernate-validator</artifactId>
-    <version>6.2.5.Final</version>
+    <artifactId>spel-validator-jakarta</artifactId>
+    <version>0.4.0-beta</version>
   </dependency>
 </dependencys>
 ```
@@ -54,7 +54,6 @@ Latest Version:
 需要满足以下两个条件，才会对带注解的元素进行校验：
 
 1. 在接口参数上使用 `@Valid` 或 `@Validated` 注解
-2. 在实体类上使用 `@SpelValid` 注解
 
 ```java
 @RestController
@@ -67,7 +66,11 @@ public class ExampleController {
   }
 
 }
+```
+
+2. 在实体类上使用 `@SpelValid` 注解
 
+```java
 @Data
 @SpelValid /*添加启动注解*/
 public class SimpleExampleParamVo {
@@ -79,7 +82,7 @@ public class SimpleExampleParamVo {
 
 如果只满足第二个条件，那么不会对任何元素进行校验。
 
-这是因为 `@SpelValid` 注解是基于 `javax.validation.Constraint` 实现的。
+这是因为 `@SpelValid` 注解是基于 `jakarta.validation.Constraint` 实现的。
 这就意味着，`@SpelValid` 和 `@NotNull`、`@NotEmpty`、`@NotBlank` 等注解一样，
 需要在 `@Valid` 或 `@Validated` 注解的支持下才会生效。
 
@@ -91,7 +94,7 @@ public class SimpleExampleParamVo {
 
 `@SpelValid` 注解包含一个属性 `condition`，支持 SpEL 表达式，计算结果必须为 `boolean` 类型。
 
-当 **表达式的算结果为true** 时，表示开启校验，默认情况下是开启的。
+当 **表达式的算结果为true** 时，表示开启校验，默认情况下也是开启的。
 
 ```java
 @Data
@@ -108,16 +111,16 @@ public class SimpleExampleParamVo {
 
 目前支持的约束注解有：
 
-|       注解        |       说明        | 对标 javax.validation |
-|:---------------:|:---------------:|:-------------------:|
-|  `@SpelAssert`  |     逻辑断言校验      |    `@AssertTrue`    |
-| `@SpelNotNull`  |    非 null 校验    |     `@NotNull`      |
-| `@SpelNotEmpty` | 集合、字符串、数组大小非空校验 |     `@NotEmpty`     |
-| `@SpelNotBlank` |    字符串非空串校验     |     `@NotBlank`     |
-|   `@SpelNull`   |   必须为 null 校验   |       `@Null`       |
-|   `@SpelSize`   |  集合、字符串、数组长度校验  |       `@Size`       |
-|   `@SpelMin`    |      即将支持       |       `@Min`        |
-|   `@SpelMax`    |      即将支持       |       `@Max`        |
+|       注解        |       说明        | 对标 jakarta.validation-api |
+|:---------------:|:---------------:|:-------------------------:|
+|  `@SpelAssert`  |     逻辑断言校验      |       `@AssertTrue`       |
+| `@SpelNotNull`  |    非 null 校验    |        `@NotNull`         |
+| `@SpelNotEmpty` | 集合、字符串、数组大小非空校验 |        `@NotEmpty`        |
+| `@SpelNotBlank` |    字符串非空串校验     |        `@NotBlank`        |
+|   `@SpelNull`   |   必须为 null 校验   |          `@Null`          |
+|   `@SpelSize`   |  集合、字符串、数组长度校验  |          `@Size`          |
+|   `@SpelMin`    |      即将支持       |          `@Min`           |
+|   `@SpelMax`    |      即将支持       |          `@Max`           |
 
 所有约束注解都包含三个默认的属性：
 
@@ -178,9 +181,9 @@ public class SimpleExampleParamVo {
 
 ::: tip 为什么 @SpelValid 注解上的 spelGroups 属性不叫 groups？
 
-因为 `@SpelValid` 注解是基于 `javax.validation.Constraint` 实现的，而 `Constraint` 中已经有一个 `groups` 属性了，故命名为 `spelGroups`。
+因为 `@SpelValid` 注解是基于 `jakarta.validation.Constraint` 实现的，而 `Constraint` 中已经有一个 `groups` 属性了，故命名为 `spelGroups`。
 
-在使用 `@SpelValid` 的时候，你可以同时使用 `groups` 和 `spelGroups` 属性，但是 `groups` 属性只能用于 `javax.validation` 的分组校验。
+在使用 `@SpelValid` 的时候，你可以同时使用 `groups` 和 `spelGroups` 属性，但是 `groups` 属性只能用于 `jakarta.validation-api` 的分组校验。
 `@SpelValid` 和 `@NotNull`、`@NotEmpty` 等注解是兄弟关系，它的 `groups` 属性同样受上层 `@Valid` 或 `@Validated` 注解的影响。
 
 :::
@@ -284,7 +287,7 @@ public class TestParamVo2 {
 
 ## 处理约束异常
 
-当校验失败时，本组件会将异常信息上报到 `javax.validation` 的异常体系中。
+当校验失败时，本组件会将异常信息上报到 `jakarta.validation-api` 的异常体系中。
 
 正常情况下，你只需要处理 `org.springframework.web.bind.MethodArgumentNotValidException`
 和 `org.springframework.validation.BindException` 这两个校验异常类就好了 ，而无需额外处理本组件的异常信息。
@@ -364,9 +367,9 @@ public class ParamTestBean {
 
 ![img.png](../image/user-g-business-exception.png)
 
-由于本组件的特殊性，所有抛出的异常信息最终都会被我们下层的校验器捕获，然后包一层 `javax.validation.ValidationException` 再抛出。
+由于本组件的特殊性，所有抛出的异常信息最终都会被我们下层的校验器捕获，然后包一层 `jakarta.validation.ValidationException` 再抛出。
 
-要从框架层面去解决这个问题，只能够脱离 `javax.validation` 的规范和 `hibernate` 的执行器来进行校验，
+要从框架层面去解决这个问题，只能够脱离 `jakarta.validation-api` 的规范和 `hibernate` 的执行器来进行校验，
 目前看来这样做的成本比较大，且会带来一些其他的影响，故暂时不考虑这样做。
 
 ### 解决方案

document/web-docs/docs/guide/user-guide.md

@@ -1,7 +1,7 @@
 {
     "name": "spel-validator",
-    "version": "0.3.0-beta",
-    "description": "一个强大的 Java 参数校验包，基于 SpEL 实现，扩展自 javax.validation 包，几乎支持所有场景下的参数校验。",
+    "version": "0.4.0-beta",
+    "description": "一个强大的 Java 参数校验包，基于 SpEL 实现，扩展自 jakarta.validation-api 包，几乎支持所有场景下的参数校验。",
     "license": "Apache-2.0",
     "type": "module",
     "scripts": {