# verify4j-spring-boot-starter

**Repository Path**: easy-work/verify4j-spring-boot-starter

## Basic Information

- **Project Name**: verify4j-spring-boot-starter
- **Description**: 尝试一下组合式注解验证参数吗
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-02-16
- **Last Updated**: 2025-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Verify4j

### 简述
```
注解声明式参数验证方案, 更具灵活性
多条件配置
more
--规则支持
    支持 when then 条件触发逻辑
    支持 为参数设置默认值
    支持 禁用参数
    支持 单字段多条件配置
    支持 手动调用验证
...
and more
--Swagger支持 | @ConditionalOnClass(SwaggerCommonConfiguration.class)
    支持 ParamVerify.alias|name|on 属性同步 ApiModelProperty.description       --参数名作为默认描述
    支持 ParamVerify.required      属性同步 ApiModelProperty.requried          --必要
    支持 ParamVerify.notBlank      属性同步 ApiModelProperty.allowEmptyValue   --非空
    支持 ParamVerify.disable       属性同步 ApiModelProperty.hidden            --禁用/隐藏
    支持 ParamVerify.in            属性同步 ApiModelProperty.allowableValues   --范围限制
    支持 ParamVerify.defaultValue  属性同步 ApiModelProperty.defaultValue      --默认值
```

### 示例

```xml
<!--引用依赖-->
<!-- https://mvnrepository.com/artifact/xyz.funnone/verify4j-spring-boot-starter -->
<dependency>
    <groupId>xyz.funnone</groupId>
    <artifactId>verify4j-spring-boot-starter</artifactId>
    <version>2.7.8</version>
</dependency>
```

##### 代码示例

```java
import lombok.Data;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import xyz.funnone.verify4j.annotation.MultiVerify;
import xyz.funnone.verify4j.annotation.ParamVerify;
import xyz.funnone.verify4j.annotation.Verify4j;
import xyz.funnone.verify4j.config.Verify4jProperties;
import xyz.funnone.verify4j.util.verify.ParamValidation;

import javax.annotation.Resource;

@RestController
@RequestMapping("app-config")
public class AppConfigController {

    @Resource
    private Verify4jProperties properties;

    /**
     * 配置查询
     * 方法前置拦截 要求key不能为null或空字符串
     */
    @ParamVerify
    @GetMapping("get")

    public String get(@ParamVerify(notBlank = true) String key) {
        return "select result";
    }

    @ParamVerify
    @PostMapping("set")
    public String set(@RequestBody AppConfigDTO dto) {
        //当type = 1 时对 AppConfigRefDTO ref字段进行内部验证
        //new ParamValidation().verify(dto.getRef());
        if ("1".equals(dto.getType())) {
            ParamValidation validation = properties.getParamValidationInstance();
            validation.verify(dto.getRef());
        }
        return "update or insert record";
    }
}

//dto
@Data
@ParamVerify    //验证此类中字段
public class AppConfigDTO {

    private Long id;

    /**
     * 上级节点
     */
    private Long superNodeId;

    /**
     * key
     * 非空验证
     * 默认值 当null时set
     */
    @ParamVerify(alias = "键名", notBlank = true, defaultValue = "sys.open")
    private String key;

    @ParamVerify(notBlank = true, message = "存入值为必填项")
    private String value;

    /**
     * 类型
     * 规定选址范围
     * 规定选值范围为枚举
     */
    @ParamVerify(
            notBlank = true, in = {"1", "2"},
            enumType = Enum.class,
            message = "类型必须在值选范围内"
    )
    private String type;

    /**
     * 修改原因
     * 当修改时候为必填 {when then}
     */
    @ParamVerify(on = "#param.id != null", notBlank = true)
    private String updateReason;

    /**
     * 子节点修改
     * 多条验证规则 {when then}
     * 例1 新增时最多插入十个子节点
     * 例2 key为app或sys开头时不允许修改子节点
     */
    @MultiVerify({
            @ParamVerify(
                    on = "#params.id == null", max = 10,
                    message = "最多插入十条子项"
            ),
            @ParamVerify(
                    on = {"#params.key.startWith('app')", "#params.key.startWith('sys')"},
                    disable = true
            )
    })
    private List<AppConfigDTO> subNodes;

    /**
     * 关联信息
     * 此类顶部不具备@ParamVerify 注解, 不进行验证
     */
    private AppConfigRefDTO ref;

}

@Data
public class AppConfigRefDTO {

    @ParamVerify(notBlank = true)
    private String content;

}


```

##### Swagger

```
文档示例
接口: /app-config/set
参数: AppConfigDTO
    {
      //属性       类型   | 变量名 |    验证  
        key   ==> String | 健名   | 非空, 默认值:sys.open;
        value ==> more...
    }
```

##### 响应示例

fail-fast:false

```json
{
  "status": 400,
  "code": 40000,
  "message": "参数有误请与文档核对",
  "more": [
    {
      "status": 400,
      "code": 40006,
      "message": "The the parameter named 'type' must in '[1, 2]'",
      "more": null
    },
    {
      "status": 400,
      "code": 40001,
      "message": "The parameter named '键名' can not been blank",
      "more": null
    }
  ]
}
```

fail-fast:true

```json
{
  "status": 400,
  "code": 40006,
  "message": "The the parameter named 'type' must in '[1, 2]'",
  "more": null
}
```

##### 配置属性示例

```yaml
paramVerify:
  # 验证失败优先返回
  failFast: true
  # 验证失败处理器
  violationHandler: xyz.funnone.verify4j.util.verify.ViolationHandler
  # 参数验证器
  paramValidation: xyz.funnone.verify4j.util.verify.ParamValidation

```

应用注解释意

* [@ParamVerify](src/main/java/xyz/funnone/verify4j/annotation/ParamVerify.java)

```
properties: 
--on = {"#param != 1"}            #前置条件(when then), 为空或者数组中有一项符合(true)时进行此项验证              
--name = "name"                   #默认取声明值
--alias = "alias"                 #别名 如中文名应用场景中字段名
--message = "message"             #提示消息
--enumType = Enum.class           #值指向枚举类, 要求当前字段在枚举值范围内
--in = {"1", "2"}                 #限制字段取值范围
--notIn = {"1", "2"}              #反向限制字段取值范围 TODO
--required = true                 #不能为null
--notBlank = true                 #字符串不能为null不能为''
--disable = true                  #屏蔽 set当前参数|字段为null
--max = 1                         #最大值  number大小 string|数组|集合长度
--min = 1                         #最大值  number大小 string|数组|集合长度
--neq = "1"                       #限制字段取值范围不能为此值
--regex = ""                      #限制字段取值范围必须符合正则
--defaultValue = "1"              #字段为空时赋值为默认值, 当defaultValue != ""
 
 
 
 !注 
    1.参数验证为aspect处理, 需要在spring-aop生命周期内
    2.引用类型验参数验证时会扫描判断类是否具备@ParamVerify 注解, 有则循环判断类中字段
    3.数组或集合中引用类型具备@ParamVerify 注解时将验证每一个对象中字段
    4.ParamValdation::verify(Object obj)验证参数时将忽略obj(引用类型或者数组集合中的引用类型)类@ParamVerify的要求
    5.默认ViolationHandler::handle验证失败处理方案为抛出RuleException异常, 可重新实现
    6.默认RuleException将被VerifyRuleResponseBodyAdvice处理转换为RuleVO做json视图响应
    7.Verify4jProperties中默认failFast=true, 可设置为false, 提示内容将会全部扫描记录并统一响应
    
调用链
    1. Aspect Around 注解环切触发参数验证
    |    xyz.funnone.verify4j.aspect.VerifyAspect
    |    
    2. 参数验证并处理 默认处理为抛出异常
    |    xyz.funnone.verify4j.util.verify.ParamValidation.methodParamVerify
    |    
    |    xyz.funnone.verify4j.util.verify.ViolationHandler.handle(xyz.funnone.verify4j.annotation.ParamVerify, java.lang.String, java.lang.Object, xyz.funnone.verify4j.enums.RuleCodeEnum, java.lang.Object...)
    |    xyz.funnone.verify4j.util.verify.ViolationHandler.handle()
    |    
    |    xyz.funnone.verify4j.exception.RuleException.RuleException(xyz.funnone.verify4j.enums.RuleCodeEnum, java.lang.Object...)
    |
    3. 异常处理与响应JSON视图
    |    xyz.funnone.verify4j.advice.VerifyRuleResponseBodyAdvice.entityTransExceptionHandle
    |    xyz.funnone.verify4j.exception.RuleException.toRuleVO
        

```

引用依赖

```xml

<dependencies>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-autoconfigure</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.12</version>
        <scope>provided</scope>
    </dependency>

    <dependency>
        <groupId>org.aspectj</groupId>
        <artifactId>aspectjweaver</artifactId>
        <version>1.9.5</version>
    </dependency>

    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.83</version>
    </dependency>

    <dependency>
        <groupId>cn.hutool</groupId>
        <artifactId>hutool-core</artifactId>
        <version>5.8.11</version>
    </dependency>

</dependencies>
```

```
作者
- @funnone

修订记录
- 2.7.8        : 初版内容 为
    by funnone
----
```

```yaml
more:
  #from http://exp-blog.com/tools/fa-bu-jar-dao-maven-zhong-yang-cang-ku-quan-liu-cheng-zhi-yin/
  deploy: mvn clean deploy -P ttyForDeploy -Dmaven.test.skip=true -e 
```