validator/README.md

154 lines
9.6 KiB
Markdown
Raw Normal View History

2024-05-17 14:09:47 +08:00
# 数据验证规则说明文档
2024-04-29 10:40:38 +08:00
2024-05-17 14:09:47 +08:00
## 验证数据结构定义
2024-05-17 14:10:43 +08:00
**`define.FieldRule`**
2024-05-17 14:09:47 +08:00
## 配置属性含义及使用方式说明
| 属性 | 含义 | 是否必须配置 | 默认值 | 使用方式 |
|:------------------------------:|:--------------------------------------:|:------:|:-------------------:|:---------------------------------------------------------------:|
| **`path`** | 要验证的字段路径 | 是 | - | 用于从数据源中获取字段值 |
| **`type`** | path所对应value的 **`数据类型`** , 支持的类型参照后续说明 | 是 | - | 用于验证字段值是否未指定类型或者是否可以转换成指定类型 |
| **`is_required`** | 是否必须存在 | 否 | false | 非必传 |
| **`allow_empty`** | 字符串类型, 空字符串是否为合法值 | 否 | false | 配合is_required验证字符串 |
| **`allow_zero`** | 数字类型(int/uint/float), 0是否为合法值 | 否 | false | 配合is_required验证数字 |
| **`allow_nil`** | 复杂类型(slice/map), nil是否为合法值 | 否 | false | 配合is_required验证复杂类型 |
| **`disable_auto_convert`** | 禁用数据类型自动转换 | 否 | false | 用于自动检测输入数据是否能转换成目标类型,搭配 **disable_rewrite** 一起使用 |
| **`disable_rewrite`** | 禁用数据值重写 | 否 | false | 若直接输入的字段值类型和目标类型不一致, 但可以转换成目标类型, 开启重写后会重写指定字段值, 不开启则只尝试参数类型转换验证 |
| **`default_value`** | 非必传字段,且字段综合判断为不存在时的默认值 | 否 | 空字符转, 空字符串等价于未配置默认值 | 非必传字段且未传时, 会使用此字段值进行填充 |
| **`disable_auto_trim_space`** | 是否禁用自动去除前后空格 | 否 | false | 未禁用时, 会通过 strings.TrimSpace进行空格去除 |
| **`required_condition_group`** | 有条件必传的必传条件 | 否 | nil | 配合is_required |
| **`value_limit`** | 数据值的基础限制 | 否 | nil | 对基础类型的基本验证 |
| **`slice_config`** | slice数据转换的配置 | 否 | nil | 针对slice数据转换的处理 |
### value_limit - 基础数据值的限制
| 属性 | 含义 | 是否必须配置 | 默认值 | 使用方式 |
|:---------------:|:----------:|:------:|:---:|:-------------------------------------------------------:|
| **`enum_list`** | 合法枚举值列表 | 否 | nil | 用于验证参数是否在枚举值列表的白名单中 |
| **`min`** | 最小值 | 否 | nil | 对于 int/uint/float64, 此值为最小值;对于 string/map/slice,此值为最小长度 |
| **`max`** | 最大值 | 否 | nil | 对于 int/uint/float64, 此值为最大值;对于 string/map/slice,此值为最大长度 |
| **`string`** | 对字符串独有的验证 | 否 | nil | 验证字符串专用配置 |
| **`map`** | 对于map独有的验证 | 否 | nil | 验证map独有配置 |
### string - 字符串独有配置
| 属性 | 含义 | 是否必须配置 | 默认值 | 使用方式 |
|:------------------------------:|:----------:|:------:|:---:|:----------------------------:|
| **`include_sub_str_list`** | 需要包含的子串列表 | 否 | nil | 验证字符串是否包含指定子串,必须全部包含才是合法值 |
| **`not_include_sub_str_list`** | 不允许包含的子串列表 | 否 | nil | 验证字符串是否包含黑名单子串,包含任意一个, 均为非法值 |
### map - map独有配置
| 属性 | 含义 | 是否必须配置 | 默认值 | 使用方式 |
|:------------------------:|:----------:|:------:|:---:|:-------------------------------:|
| **`include_field_list`** | 需要包含的key列表 | 否 | nil | map数据中必须包含的key列表, 必须全部包含才是一个合法值 |
### slice_config - slice数据转换的处理
| 属性 | 含义 | 是否必须配置 | 默认值 | 使用方式 |
|:--------------------------:|:------------:|:------:|:-----:|:---------------------------------------------------------------------:|
| **`slice_mode`** | 输入的slice数据模式 | 是 | - | REAL - 输入直接是slice MARSHAL - json序列化之后的字符串 WITH_SPLIT_CHAR - 使用指定字符串分隔 |
| **`disable_ignore_empty`** | 忽略空字符串 | 否 | false | model = WITH_SPLIT_CHAR, 忽略分割后的空字符串 |
| **`split_char`** | 分隔符 | 否 | nil | model = WITH_SPLIT_CHAR, 分割字符串的分隔符 |
## 各个字段使用场景实例
### is_required - 数据是否必须存在
此属性搭配 **`allow_empty`** 、**`allow_zero`**、**`allow_nil`** 使用
关于属性判定为 **`不存在`** 的场景有如下几个:
- 输入的数据源中, 不存在指定字段
- 输入的数据源中, 存在指定字段:
- 字段类型为 **`int/float/uint`**, 切 **value = 0** , 同时 **allow_zero=false** , 则等价于参数未传
- 字段类型为 **`string`**, 切 **value = ""** , 同时 **allow_empty=false** , 则等价于参数未传
- 字段类型为 **`slice/map`**, 切 **value = nil** , 同时 **allow_nil=false** , 则等价于参数未传
- 本身配置 is_required = false, 但是验证中 命中 **`required_condition_group``** 验证条件, 等价于 is_required = true
### disable_auto_convert - 数据类型自动转换控制
```go
sourceData := map[string]any{
"num": "1"
}
validateRule.Path = "num"
validateRule.Type = "int"
```
disable_auto_convert = false 时, 即未禁用自动转换, 会返回如下数据
```go
map[string]any{
"num": 1
}
```
disable_auto_convert = true 时, 即未禁用自动转换, 会返回参数验证错误
### disable_rewrite - 数据验证结果重写控制
前提是 disable_auto_convert = false, 即允许参数的自动转换, 会自动使用转换后的数据值, 覆盖输入的数据值
输入数据 :
```go
sourceData := map[string]any{
"num": "1"
}
validateRule.Type = "int"
```
disable_rewrite = false 时, 即允许重写, 验证完成会返回如下数据:
```go
map[string]any{
"num": 1
}
```
disable_rewrite = true 时, 即允许不重写, 验证完成会将sourceData原样返回
### disable_auto_trim_space - 自动去除前后空格
disable_auto_trim_space = false, 即未禁用去除前后空格, 则
string(" 1 ") => int(1) , 转换关系成立
disable_auto_trim_space = true, 即禁用去除前后空格, 则
string(" 1 ") => int(1) , 转换关系不成立
## 支持配置的数据类型
| 配置值 | 实际映射类型 |
|:-----------------:|:--------------------:|
| int | int64 |
| uint | uint64 |
| float | float64 |
| bool | bool |
| string | string |
| []int | []int64 |
| []uint | []uint64 |
| []float | []float64 |
| []bool | []bool |
| []string | []string |
| []any | []any |
| map[string]string | map[string]string |
| map[string]int | map[string]int64 |
| map[string]uint | map[string]uint64 |
| map[string]float | map[string]float64 |
| map[string]bool | map[string]bool |
| map[string]any | map[string]any |
| map[string][]any | map[string][]any |
| map[any]any | map[any]any |
| any | any |
| []int_split | []int64, 需要配合数组转换配置 |
| []uint_split | []uint64, 需要配合数组转换配置 |
| []float_split | []float, 需要配合数组转换配置 |
| []bool_split | []bool, 需要配合数组转换配置 |
| []string_split | []string, 需要配合数组转换配置 |
| [][]any | [][]any |
| []map[any]any | []map[any]any |
| []map[string]any | []map[string]any |