Echo 系列教程——定制篇2：自定义 Validator，进行输入校验
上一篇讲 Binder 时提到，参数自动绑定和校验是 Web 框架很重要的两个功能，可以极大的提升开发速度，并更好的保证数据的可靠性（服务端数据校验很重要）。本节，我们就一起看看如何自定义 Echo 的表单校验功能。
不同于 Binder，Echo 并没有内置数据校验的能力，也就是没有默认的 Validator 实现。然而，你可以很方便的集成第三方的数据校验库。跟 Binder 类似，Echo 提供了一个 Validator 接口，方便将第三方数据校验库集成进来。
Validator interface {
Validate(i interface{}) error
}
通过这个实现这个接口，可以很方便的将任何第三方数据校验库集成到 Echo 中。在 Awesome-Go 上可以找到第三方数据校验库：https://github.com/avelino/awesome-go#validation。本文我们使用最流行的 https://github.com/go-playground/validator 库来讲解。
go-playground/validator
这是一个 Go 结构体及字段校验器，包括：跨字段和跨结构体校验，Map，切片和数组，是目前校验器相关库中 Star 数最高的一个，对国际化支持也很好，建议大家使用它。
它具有以下独特功能：
- 通过使用验证标签（tag）或自定义验证程序进行跨字段和跨结构体验证；
- 切片，数组和 map，可以验证任何的多维字段或多层级；
- 能够深入（多维）了解 map 键和值以进行验证；
- 通过在验证之前确定其基础类型来处理接口类型；
- 处理自定义字段类型，例如 sql driver Valuer；
- 别名验证标签，允许将多个验证映射到单个标签，以便更轻松地定义结构上的验证；
- 提取自定义定义的字段名称，例如可以指定在验证时提取 JSON 名称，并将其用于结果 FieldError 中；
- 可自定义的 i18n 错误消息；
- gin Web 框架的默认验证器；
一个简单的例子
通过一个简单例子来看看如何使用该库。
package main
import (
"fmt"
"flag"
"github.com/go-playground/validator/v10"
)
type User struct {
Name string `validate:"required"`
Age uint `validate:"gte=1,lte=130"`
Email string `validate:"required,email"`
}
var (
name string
age uint
email string
)
func init() {
flag.StringVar(&name, "name", "", "输入名字")
flag.UintVar(&age, "age", 0, "输入年龄")
flag.StringVar(&email, "email", "", "输入邮箱")
}
func main() {
flag.Parse()
user := &User{
Name: name,
Age: age,
Email: email,
}
validate := validator.New()
err := validate.Struct(user)
if err != nil {
fmt.Println(err)
}
}
执行如下命令，运行代码：
go run main.go -name studygolang -age 7 -email polaris@studygolang.com
什么都没有输出，表示一切正常。如果我们提供一个非法的邮箱地址：
go run main.go -name studygolang -age 7 -email polaris@studygolang
输出如下错误：
Key: 'User.Email' Error:Field validation for 'Email' failed on the 'email' tag
错误显示不友好。怎么能够更友好，并进行国际化呢？
国际化（i18n）
在介绍校验库错误消息国际化之前，有一个概念需要了解下，那就是 CLDR。
什么是 CLDR？
它是 i18n 的一套核心规范（ Common Locale Data Respository），即通用的本地化数据存储库，什么意思呢？比如我们的手机，电脑都可以选择语言模式为 英语、汉语、日语、法语等等，这套操作背后的规范，就是 CLDR；CLDR 是以 Unicode 的编码标准作为前提，将多国的语言文字进行编码的。
看看官方对于 CLDR 的说明，官方网址：http://cldr.unicode.org/
Unicode CLDR 提供了支持世界语言的软件的关键构建块，并且具有最大和最广泛的本地设置数据标准存储库。大量的公司使用此数据进行软件的国际化和本地化，使它们的软件适应此类通用软件任务的不同语言的约定。
需要进行国际化和本地化的主要包括：
- 用于格式化和解析的特定于语言环境的模式：日期，时间，时区，数字和货币值，度量单位，…
- 名称的翻译：语言，脚本，国家和地区，货币，时代，月份，工作日，白天，时区，城市和时间单位，表情符号字符和序列（和搜索关键字），…
- 语言和文字信息：使用的字符；复数情况；性别；大写；分类和搜索规则；写作方向；音译规则；拼写数字的规则；将文本分割成字符，单词和句子的规则；键盘布局…
- 国家/地区信息：语言使用情况，货币信息，日历首选项，星期惯例等…
- 有效性：Unicode 语言环境，语言，脚本，区域和扩展名的定义，别名和有效性信息，…
CLDR 的 Go 语言实现
本文讲解的校验库是 go-playground 这个组织创建的，它们还提供了其他的一些有用库，其中就包括了 CLDR 的 Go 语言实现，这就是 locales 。
该库是从 CLDR 项目生成的一组语言环境，可以单独使用或在 i18n 软件包中使用；这些是专为 https://github.com/go-playground/universal-translator 构建的，但也可以单独他用。
这引出了该组织的另外一个库：universal-translator 。
universal-translator ：一个使用 CLDR 数据+复数规则（比如英语很多复数规则是加 s）的 Go i18n 转换器（翻译器）。该库是 locales 的薄包装，以便存储和翻译文本，供你在应用程序中使用。
universal-translator 简明教程
这个通用的翻译器包主要包含了两个核心数据结构：Translator 接口和 UniversalTranslator 结构体，其他的是错误类型。我们先看 Translator 接口。（注意，该包的包名是 ut）
Translator 接口
type Translator interface {
locales.Translator
// adds a normal translation for a particular language/locale
// {#} is the only replacement type accepted and are ad infinitum
// eg. one: '{0} day left' other: '{0} days left'
Add(key interface{}, text string, override bool) error
// adds a cardinal plural translation for a particular language/locale
// {0} is the only replacement type accepted and only one variable is accepted as
// multiple cannot be used for a plural rule determination, unless it is a range;
// see AddRange below.
// eg. in locale 'en' one: '{0} day left' other: '{0} days left'
AddCardinal(key interface{}, text string, rule locales.PluralRule, override bool) error
// adds an ordinal plural translation for a particular language/locale
// {0} is the only replacement type accepted and only one variable is accepted as
// multiple cannot be used for a plural rule determination, unless it is a range;
// see AddRange below.
// eg. in locale 'en' one: '{0}st day of spring' other: '{0}nd day of spring'
// - 1st, 2nd, 3rd...
AddOrdinal(key interface{}, text string, rule locales.PluralRule, override bool) error
// adds a range plural translation for a particular language/locale
// {0} and {1} are the only replacement types accepted and only these are accepted.
// eg. in locale 'nl' one: '{0}-{1} day left' other: '{0}-{1} days left'
AddRange(key interface{}, text string, rule locales.PluralRule, override bool) error
// creates the translation for the locale given the 'key' and params passed in
T(key interface{}, params ...string) (string, error)
// creates the cardinal translation for the locale given the 'key', 'num' and 'digit' arguments
// and param passed in
C(key interface{}, num float64, digits uint64, param string) (string, error)
// creates the ordinal translation for the locale given the 'key', 'num' and 'digit' arguments
// and param passed in
O(key interface{}, num float64, digits uint64, param string) (string, error)
// creates the range translation for the locale given the 'key', 'num1', 'digit1', 'num2' and
// 'digit2' arguments and 'param1' and 'param2' passed in
R(key interface{}, num1 float64, digits1 uint64, num2 float64, digits2 uint64, param1, param2 string) (string, error)
// VerifyTranslations checks to ensures that no plural rules have been
// missed within the translations.
VerifyTranslations() error
}
关于该接口需要需要如下几点说明
- 内嵌了 locales.Translator 接口；
- 几类复数规则：cardinal plural（基数复数规则，即单数和复数两种）；ordinal plural（序数复数规则，如 1st, 2nd, 3rd…）；ordinal plural （范围复数规则，如 0-1）。对中文来说，这里大部分不需要。
- 几个 Add 方法，和上面几类规则对应；一个 key 和 一个带站位符的 text；
- 单字符的几个方法和 Add 几个方法的对应关系：T -> Add；C -> AddCardinal；O -> AddOrdinal；R -> AddRange ；表示用具体的值替换 key 表示的文本 text 中的占位符。
- 以上方法参数中，num 表示占位符处的值，但对于有复数形式的语言，这个值必须符合复数语言的规范，否则会报错；digits 表示 num 值的有效数字（或者说小数位数）；
- VerifyTranslations 确保翻译库中没有缺少对应的语言规则；
UniversalTranslator 结构体
它用于保存所有语言环境和翻译数据。该结构体方法不多，我们关注几个核心的。
func New(fallback locales.Translator, supportedLocales ...locales.Translator) *UniversalTranslator
New 返回一个 UniversalTranslator 实例，该实例具有后备语言环境（fallback）和应支持的语言环境（supportedLocales）。可以看到，New 函数接收的参数是 locales.Translator 类型，因此我们肯定需要用到 locales 包。
得到 UniversalTranslator 实例后，需要获得 universal-translator 包中的 Translator 接口实例，这就用到了下面几个方法。
1）GetTranslator
func (t *UniversalTranslator) GetTranslator(locale string) (trans Translator, found bool)
返回给定语言环境的指定翻译器，如果未找到，则返回后备语言环境的翻译器（即 New 中的 fallback）。
2）GetFallback
func (t *UniversalTranslator) GetFallback() Translator
直接返回后备语言环境的翻译器。
3）FindTranslator
func (t *UniversalTranslator) FindTranslator(locales ...string) (trans Translator, found bool)
尝试根据语言环境数组查找翻译器，并返回它可以找到的第一个翻译器，否则返回后备翻译器。
总结来说，New 函数加上这三个方法，相当于是 locales.Translator 到 ut.Translator 的转换。
示例
通过一个实际的例子来学习下这两个包的使用。
package main
import (
"flag"
"fmt"
"github.com/go-playground/locales"
"github.com/go-playground/locales/en"
"github.com/go-playground/locales/zh"
"github.com/go-playground/locales/zh_Hant_TW"
ut "github.com/go-playground/universal-translator"
)
var universalTraslator *ut.UniversalTranslator
func main() {
acceptLanguage := flag.String("language", "zh", "语言")
flag.Parse()
e := en.New()
universalTraslator = ut.New(e, e, zh.New(), zh_Hant_TW.New())
translator, _ := universalTraslator.GetTranslator(*acceptLanguage)
switch *acceptLanguage {
case "zh":
translator.Add("welcome", "欢迎 {0} 来到 studygolang.com！", false)
translator.AddCardinal("days", "你只剩 {0} 天时间可以注册", locales.PluralRuleOther, false)
translator.AddOrdinal("day-of-month", "第{0}天", locales.PluralRuleOther, false)
translator.AddRange("between", "距离 {0}-{1} 天", locales.PluralRuleOther, false)
case "en":
translator.Add("welcome", "Welcome {0} to studygolang.com.", false)
translator.AddCardinal("days", "You have {0} day left to register", locales.PluralRuleOne, false)
translator.AddOrdinal("day-of-month", "{0}st", locales.PluralRuleOne, false)
translator.AddRange("between", "It's {0}-{1} days away", locales.PluralRuleOther, false)
}
fmt.Println(translator.T("welcome", "polaris"))
fmt.Println(translator.C("days", 1, 0, translator.FmtNumber(1, 0)))
fmt.Println(translator.O("day-of-month", 1, 0, translator.FmtNumber(1, 0)))
fmt.Println(translator.R("between", 1, 0, 2, 0, translator.FmtNumber(1, 0), translator.FmtNumber(2, 0)))
}
主要通过这个例子说明相关函数的使用。
- 根据 acceptLanguage 的不同值，设置不同的语言文案；
- 对于中文来说，没有复数，因此 AddXX 三个方法的第二个参数都是 locales.PluralRuleOther，表示该语言环境没有复数形式；
- 英文环境下，PluralRule 规则不能乱填，根据实际情况来；
- 最后在实际填充值时，num 表示占位符要填入的值，digits 表示 num 这个值最终要保留几位小数；
- FmtNumber 方法的参数需要和前面的 num 和 digits 对应上，第一个参数是 num 的值，第二个是 digits 的值；
Validator 怎么和以上两个库集成提供 i18n
Validator 库提供了相应的子库，对以上两个库进行了封装。比如中文的库：github.com/go-playground/validator/translations/zh ，这些子库提供了一个 RegisterDefaultTranslations ，为所有内置标签的验证器注册一组默认翻译。
func RegisterDefaultTranslations(v *validator.Validate, trans ut.Translator) (err error)
具体怎么做？还是看最开始的例子，其他不变，main 函数改为如下：
func main() {
flag.Parse()
user := &User{
Name: name,
Age: age,
Email: email,
}
validate := validator.New()
e := en.New()
uniTrans := ut.New(e, e, zh.New(), zh_Hant_TW.New())
translator, _ := uniTrans.GetTranslator("zh")
zh_translate.RegisterDefaultTranslations(validate, translator)
err := validate.Struct(user)
if err != nil {
errs := err.(validator.ValidationErrors)
for _, err := range errs {
fmt.Println(err.Translate(translator))
}
}
}
注册一个默认的中文翻译器，在校验出错后，对错误进行翻译。不输入任何参数运行程序，输出：
Name为必填字段 Age必须大于或等于1 Email为必填字段
大功告成。
将 Validator 集成到 Echo 中
首先，需要定义一个类型，实现 Echo 的接口 Validator ：
type CustomValidator struct {
once sync.Once
validate *validator.Validate
}
func (c *CustomValidator) Validate(i interface{}) error {
c.lazyInit()
return c.validate.Struct(i)
}
func (c *CustomValidator) lazyInit() {
c.once.Do(func() {
c.validate = validator.New()
})
}
因为 validator.Validate 实例化做了不少事情，这里将实例化推迟到使用时。简单几行代码就实现了一个自定义的 Validator。
接下来和 Echo 集成起来就很容易了。
e := echo.New()
e.Validator = &CustomValidator{}
之后就可以在需要进行表单校验的地方通过 ctx.Validate() 进行校验。
自此我们完成了 Validator 集成到 Echo 的功能。
还剩最后一块内容，那就是校验错误信息的国际化显示。国际化相关的内容，上面有了较详细的介绍，Validator 集成到 Echo 后如何国际化我们在后面实战篇再讲。
完整代码见：https://github.com/polaris1119/go-echo-example/blob/master/pkg/validator/validator.go。
