From d61144d9f3464a73b8db697bb5522b12dd9789c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 17 May 2024 14:09:47 +0800 Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0README=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 154 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 152 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3dc781e..662547e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,153 @@ -# validator +# 数据验证规则说明文档 -数据验证规则 \ No newline at end of file +## 验证数据结构定义 + +**`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 |