docs: 完善文档 使用指南

Author: stick-i

document/web-docs/docs/guide/getting-started.md

@@ -18,7 +18,7 @@ Latest Version:
   <dependency>
     <groupId>org.hibernate.validator</groupId>
     <artifactId>hibernate-validator</artifactId>
-    <version>${hibernate-validator.version}</version>
+    <version>6.2.5.Final</version>
   </dependency>
 
   <dependency>

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

@@ -1,5 +1,56 @@
 # SpEL 表达式
 
-暂时没写
+本章只介绍一些重要的 SpEL 表达式用法，更详细的使用说明请参考官方文档。
 
-可以先看看官方文档：[Spring Expression Language (SpEL)](https://docs.spring.io/spring-framework/reference/core/expressions.html)
+官方文档：[Spring Expression Language (SpEL)](https://docs.spring.io/spring-framework/reference/core/expressions.html)
+
+::: tip
+
+如果你的 IDEA 版本比较新，那么不出意外的话，IDEA 能够识别到表达式，并且会给出提示，也具备引用的功能。
+
+:::
+
+## 调用静态方法
+
+调用静态方法的语法为：`T(全类名).方法名(参数)`。
+
+```java
+@Data
+@SpelValid
+public class SimpleExampleParamVo {
+
+  /**
+   * 枚举值字段校验
+   */
+  @SpelAssert(assertTrue = " T(cn.sticki.enums.UserStatusEnum).getByCode(#this.userStatus) != null ", message = "用户状态不合法")
+  private Integer userStatus;
+
+  // 中文算两个字符，英文算一个字符，要求总长度不超过 10
+  // 调用外部静态方法进行校验
+  @SpelAssert(assertTrue = "T(cn.sticki.util.StringUtil).getLength(#this.userName) <= 10", message = "用户名长度不能超过10")
+  private String userName;
+
+}
+```
+
+## 调用 Spring Bean
+
+[开启 Spring Bean 支持](user-guide.md#开启对-spring-bean-的支持)后，即可在 SpEL 表达式中调用 Spring Bean。
+
+调用 Bean 的语法为：`@beanName.methodName(参数)`。
+
+```java
+@Data
+@SpelValid
+public class SimpleExampleParamVo {
+
+  /**
+   * 调用 userService 的 getById 方法，判断用户是否存在
+   * 校验失败时，提示信息为：用户不存在
+   * 这里只是简单举例，实际开发中不建议这样判断用户是否存在
+   */
+  @SpelAssert(assertTrue = "@userService.getById(#this.userId) != null", message = "用户不存在")
+  private Long userId;
+
+}
+```

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

@@ -1,13 +1,50 @@
 # 使用指南
 
-::: tip
+::: warning
 
 本组件的目的不是代替 `javax.validation` 的校验注解，而是作为一个扩展，方便某些场景下的参数校验。
 
 原则上来说，能够使用 `javax.validation` 处理的场景就不应该使用 `spel-validator` 。
 
 :::
 
+## 添加依赖
+
+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)
+
+大多少情况下，你只需要添加以下两个依赖：
+
+```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>
+  </dependency>
+</dependencys>
+```
+
+如果你的项目中没有任何对于Spring的依赖，那么你需要额外添加一个对SpEL的依赖：
+
+```xml
+<dependencys>
+  <!-- SpEL 依赖项 -->
+  <dependency>
+    <groupId>org.springframework</groupId>
+    <artifactId>spring-expression</artifactId>
+    <version>${spring.version}</version>
+  </dependency>
+</dependencys>
+```
+
 ## 开启约束校验
 
 需要满足以下两个条件，才会对带注解的元素进行校验：
@@ -46,6 +83,49 @@ public class SimpleExampleParamVo {
 
 所以，如果需要使用 `SpEL Validator` 进行校验，需要同时满足上述两个条件。
 
+### 设置开启条件
+
+`@SpelValid` 注解包含一个属性 `condition`，支持 SpEL 表达式。
+
+当 **表达式的算结果为true** 时，表示开启校验，默认情况下开启校验。
+
+```java
+@Data
+@SpelValid(condition = "1 > 0") /*设置开启校验的条件*/
+public class SimpleExampleParamVo {
+  // ...
+}
+```
+
+这里的 `condition` 字段同样支持上下文引用，具体使用方式参考 [引用上下文字段](#引用上下文字段)。
+
+
+## 引用上下文字段
+
+设计这套组件的初衷，就是为了满足一些需要判断另一个字段的值来决定当前字段是否校验的场景。
+
+在组件内部，将当前校验的整个类对象作为了 SpEL 表达式解析过程中的根对象，所以在表达式中可以直接引用类中的任意字段。
+
+通过 `#this.fieldName` 的方式来引用当前类对象的字段。
+
+```java
+@Data
+@SpelValid
+public class SimpleExampleParamVo {
+
+  private boolean switchAudio;
+
+  /**
+   * 此处引用了上面的 switchAudio 字段
+   * 当 switchAudio 字段的值为 true 时，才会校验 audioContent 是否为null
+   */
+  @SpelNotNull(condition = "#this.switchAudio == true")
+  private Object audioContent;
+
+}
+```
+
+
 ## 使用约束注解
 
 目前支持的约束注解有：
@@ -85,31 +165,6 @@ public class SimpleExampleParamVo {
 }
 ```
 
-## 引用上下文字段
-
-设计这套组件的初衷，就是为了满足一些需要判断另一个字段的值来决定当前字段是否校验的场景。
-
-在组件内部，将当前校验的整个类对象作为了 SpEL 表达式解析过程中的根对象，所以在表达式中可以直接引用类中的任意字段。
-
-通过 `#this.fieldName` 的方式来引用当前类对象的字段。
-
-```java
-@Data
-@SpelValid
-public class SimpleExampleParamVo {
-
-  private boolean switchAudio;
-
-  /**
-   * 此处引用了上面的 switchAudio 字段
-   * 当 switchAudio 字段的值为 true 时，才会校验 audioContent 是否为null
-   */
-  @SpelNotNull(condition = "#this.switchAudio == true")
-  private Object audioContent;
-
-}
-```
-
 ## 分组校验
 
 待补充
@@ -170,34 +225,18 @@ public class TestParamVo2 {
 }
 ```
 
-## 调用静态方法
+## 处理异常
 
-利用 SpEL 的特性，可以调用静态方法进行校验。
+待补充
 
-调用静态方法的格式为：`T(全类名).方法名(参数)`。
+当校验失败时，本组件会将异常信息上报到 `javax.validation` 的异常体系中。
 
-如果你的 IDEA 版本比较新，那么不出意外的话，IDEA 能够识别到表达式，并且会给出提示，也具备引用的功能。
+所以正常情况下，你无需添加额外的异常处理逻辑。
 
 ```java
-@Data
-@SpelValid
-public class SimpleExampleParamVo {
-
-  /**
-   * 枚举值字段校验
-   */
-  @SpelAssert(assertTrue = " T(cn.sticki.enums.UserStatusEnum).getByCode(#this.userStatus) != null ", message = "用户状态不合法")
-  private Integer userStatus;
-
-  // 中文算两个字符，英文算一个字符，要求总长度不超过 10
-  // 调用外部静态方法进行校验
-  @SpelAssert(assertTrue = "T(cn.sticki.util.StringUtil).getLength(#this.userName) <= 10", message = "用户名长度不能超过10")
-  private String userName;
-
-}
 ```
 
-## 调用 Spring Bean
+## 开启对 Spring Bean 的支持
 
 默认情况下，解析器无法识别 SpEL 表达式中的 Spring Bean。
 
@@ -216,22 +255,4 @@ public class Application {
 }
 ```
 
-开启 Spring Bean 支持后，即可在 SpEL 表达式中调用 Spring Bean。
-
-> 表达式中的 Bean 名称需要以 `@` 开头
-
-```java
-@Data
-@SpelValid
-public class SimpleExampleParamVo {
-
-  /**
-   * 调用 userService 的 getById 方法，判断用户是否存在
-   * 校验失败时，提示信息为：用户不存在
-   * 这里只是简单举例，实际开发中不建议这样判断用户是否存在
-   */
-  @SpelAssert(assertTrue = "@userService.getById(#this.userId) != null", message = "用户不存在")
-  private Long userId;
-
-}
-```
+关于使用方法，请参考 [调用 Spring Bean](spel.md#调用-spring-bean)。