From 58ff03cc61d39f558a72d8e67b62cdcf8b552aea Mon Sep 17 00:00:00 2001 From: Inhere Date: Sun, 8 May 2022 00:02:32 +0800 Subject: [PATCH] style: update zh and en readme, add more docs --- README.md | 32 +++++++++++++------ README.zh-CN.md | 83 ++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 94 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index ab8ea6a..9fe28e9 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,8 @@ `validate` is a generic Go data validate and filter tool library. - Support quick validate `Map`, `Struct`, `Request`(`Form`, `JSON`, `url.Values`, `UploadedFile`) data + - Supports checking each child value in a slice. eg: `v.StringRule("tags.*", "required|string|minlen:1")` + - Validating `http.Request` automatically collects data based on the request `Content-Type` value - Support filter/sanitize data before validate - Support add custom filter/validator func - Support scene settings, verify different fields in different scenes @@ -32,13 +34,11 @@ ## Validate Struct -### Config the struct use tags - -Use the `validate` tag of the structure, you can quickly verify a structure data. +Use the `validate` tag of the structure, you can quickly config a structure. -**`v1.2.1+` Update**: +### Config the struct use tags -Can use `message` and `label` tags, config the field translates and error messages on struct. +Field translations and error messages for structs can be quickly configured using the `message` and `label` tags. - Support configuration field mapping through structure tag, read the value of `json` tag by default - Support configuration error message via structure's `message` tag @@ -235,7 +235,8 @@ func main() { ## Validate Request -If it is an HTTP request, you can quickly validate the data and pass the verification. Then bind the secure data to the structure. +If it is an HTTP request, you can quickly validate the data and pass the verification. +Then bind the secure data to the structure. ```go package main @@ -320,7 +321,7 @@ v := d.Validation() ## More Usage -### Validate error +### Validate Error `v.Errors` is map data, top key is field name, value is `map[string]string`. @@ -415,7 +416,7 @@ type GlobalOption struct { } ``` -Usage: +**Usage**: ```go // change global opts @@ -433,9 +434,11 @@ validate.Config(func(opt *validate.GlobalOption) { import "github.com/gookit/validate/locales/zhcn" // for all Validation. -// NOTICE: must be register before on validate.New() +// NOTICE: must be registered before on validate.New(), it only need call at once. zhcn.RegisterGlobal() +// ... ... + v := validate.New() // only for current Validation @@ -464,7 +467,16 @@ v.AddMessages(map[string]string{ }) ``` -- For a struct +- Use struct tags: `message, label` + +```go +type UserForm struct { + Name string `validate:"required|minLen:7" label:"User Name"` + Email string `validate:"email" message:"email is invalid" label:"User Email"` +} +``` + +- Use struct method `Messages()` ```go // Messages you can custom validator error messages. diff --git a/README.zh-CN.md b/README.zh-CN.md index b3cdd2b..dfa5ad7 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -9,9 +9,10 @@ Go通用的数据验证与过滤库，使用简单，内置大部分常用验证器、过滤器，支持自定义消息、字段翻译。 +- 简单方便，支持前置验证检查, 支持添加自定义验证器 - 支持验证 `Map` `Struct` `Request`（`Form`，`JSON`，`url.Values`, `UploadedFile`）数据 + - 支持检查 slice 中的每个子项值. eg: `v.StringRule("tags.*", "required|string|minlen:1")` - 验证 `http.Request` 时会自动根据请求数据类型 `Content-Type` 收集数据 -- 简单方便，支持前置验证检查, 支持添加自定义验证器 - 支持将规则按场景进行分组设置，不同场景验证不同的字段 - 已经内置了超多（**>70** 个）常用的验证器，查看 [内置验证器](#built-in-validators) - 支持在进行验证前对值使用过滤器进行净化过滤，适应更多场景 @@ -34,18 +35,17 @@ Please see the English introduction **[README](README.md)** ## 验证结构体(Struct) -结构体可以实现3个接口方法，方便做一些自定义： +在结构体上添加 `validate`标签，可以快速对一个结构体进行验证设置。 -- `ConfigValidation(v *Validation)` 将在创建验证器实例后调用 -- `Messages() map[string]string` 可以自定义验证器错误消息 -- `Translates() map[string]string` 可以自定义字段映射/翻译 +### 使用标签快速配置验证 -**`v1.2.1+` 更新**: +可以搭配使用 `message` 和 `label` 标签，快速配置结构体的字段翻译和错误消息。 - 支持通过结构体配置字段输出名称，默认读取 `json` 标签的值 - 支持通过结构体的 `message` tag 配置错误消息 - 支持通过结构体的 `label` tag 字段映射/翻译 +**代码示例**: ```go package main @@ -59,18 +59,60 @@ import ( // UserForm struct type UserForm struct { - Name string `validate:"required|minLen:7"` + Name string `validate:"required|min_len:7" message:"required:{field} is required" label:"用户名称"` Email string `validate:"email" message:"email is invalid" label:"用户邮箱"` - Age int `validate:"required|int|min:1|max:99" message:"int:age must int| min: age min value is 1"` + Age int `validate:"required|int|min:1|max:99" message:"int:age must int|min:age min value is 1"` CreateAt int `validate:"min:1"` + Safe int `validate:"-"` // 标记字段安全无需验证 + UpdateAt time.Time `validate:"required" message:"update time is required"` + Code string `validate:"customValidator"` + // 结构体嵌套 + ExtInfo struct{ + Homepage string `validate:"required" label:"用户主页"` + CityName string + } `validate:"required" label:"扩展信息"` +} + +// CustomValidator custom validator in the source struct. +func (f UserForm) CustomValidator(val string) bool { + return len(val) == 4 +} +``` + +### 使用结构体方法配置验证 + +结构体可以实现3个接口方法，方便做一些自定义： + +- `ConfigValidation(v *Validation)` 将在创建验证器实例后调用 +- `Messages() map[string]string` 可以自定义验证器错误消息 +- `Translates() map[string]string` 可以自定义字段映射/翻译 + +**代码示例**: + +```go +package main + +import ( + "fmt" + "time" + + "github.com/gookit/validate" +) + +// UserForm struct +type UserForm struct { + Name string `validate:"required|minLen:7"` + Email string `validate:"email"` + Age int `validate:"required|int|min:1|max:99"` Safe int `validate:"-"` + CreateAt int `validate:"min:1"` UpdateAt time.Time `validate:"required"` Code string `validate:"customValidator"` // 使用自定义验证器 // 结构体嵌套 ExtInfo struct{ Homepage string `validate:"required"` CityName string - } + } `validate:"required"` } // CustomValidator 定义在结构体中的自定义验证器 @@ -80,7 +122,10 @@ func (f UserForm) CustomValidator(val string) bool { // ConfigValidation 配置验证 // - 定义验证场景 +// - 也可以添加验证设置 func (f UserForm) ConfigValidation(v *validate.Validation) { + // v.StringRule() + v.WithScenes(validate.SValues{ "add": []string{"ExtInfo.Homepage", "Name", "Code"}, "update": []string{"ExtInfo.CityName", "Name"}, @@ -103,7 +148,11 @@ func (f UserForm) Translates() map[string]string { "ExtInfo.Homepage": "用户主页", } } +``` +### 创建和调用验证 + +```go func main() { u := &UserForm{ Name: "inhere", @@ -111,6 +160,7 @@ func main() { // 创建 Validation 实例 v := validate.Struct(u) + // 或者使用 // v := validate.New(u) if v.Validate() { // 验证成功 @@ -335,7 +385,7 @@ type GlobalOption struct { } ``` -如何配置: +**如何配置**: ```go // 更改全局选项 @@ -353,9 +403,11 @@ type GlobalOption struct { import "github.com/gookit/validate/locales/zhcn" // for all Validation. -// NOTICE: must be register before on validate.New() +// NOTICE: 必须在调用 validate.New() 前注册, 它只需要一次调用。 zhcn.RegisterGlobal() +// ... ... + v := validate.New() // only for current Validation @@ -384,6 +436,15 @@ v.AddMessages(map[string]string{ }) ``` +- 使用结构体标签: `message, label` + +```go +type UserForm struct { + Name string `validate:"required|minLen:7" label:"用户名称"` + Email string `validate:"email" message:"email is invalid" label:"用户邮箱"` +} +``` + - 结构体可以通过 `Messages()` 方法添加 ```go