validator/README.md

# 数据验证规则说明文档

## 验证数据结构定义

**`define.FieldRule`**

## 配置属性含义及使用方式说明

|               属性               |                   含义                   | 是否必须配置 |         默认值         |                              使用方式                               |
|:------------------------------:|:--------------------------------------:|:------:|:-------------------:|:---------------------------------------------------------------:|
|           **`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   |