Go 语言 Web 框架 Echo 系列：定制篇2—自定义 Validator

上一篇讲 Binder 时提到，参数自动绑定和校验是 Web 框架很重要的两个功能，可以极大的提升开发速度，并更好的保证数据的可靠性（服务端数据校验很重要）。本节，我们就一起看看如何自定义 Echo 的表单校验功能。

不同于 Binder，Echo 并没有内置数据校验的能力，也就是没有默认的 Validator 实现。然而，你可以很方便的集成第三方的数据校验库。跟 Binder 类似，Echo 提供了一个 Validator 接口，方便将第三方数据校验库集成进来。

 Validator interface {
   validate (i interface{}) error
}

通过这个实现这个接口，可以很方便的将任何第三方数据校验库集成到 Echo 中。在 Awesome-Go 上可以找到第三方数据校验库：#validation。本文我们使用最流行的库来讲解。

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 的说明，官方网址：

需要进行国际化和本地化的主要包括：

用于格式化和解析的特定于语言环境的模式：日期，时间，时区，数字和货币值，度量单位，…
名称的翻译：语言，脚本，国家和地区，货币，时代，月份，工作日，白天，时区，城市和时间单位，表情符号字符和序列（和搜索关键字），…
语言和文字信息：使用的字符；复数情况；性别；大写；分类和搜索规则；写作方向；音译规则；拼写数字的规则；将文本分割成字符，单词和句子的规则；键盘布局…
国家/地区信息：语言使用情况，货币信息，日历首选项，星期惯例等…
有效性：Unicode 语言环境，语言，脚本，区域和扩展名的定义，别名和有效性信息，…

CLDR 的 Go 语言实现

本文讲解的校验库是 go-playground 这个组织创建的，它们还提供了其他的一些有用库，其中就包括了 CLDR 的 Go 语言实现，这就是 locales。

该库是从 CLDR 项目生成的一组语言环境，可以单独使用或在 i18n 软件包中使用；这些是专为构建的，但也可以单独他用。

这引出了该组织的另外一个库：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 后如何国际化我们在后面实战篇再讲。

完整代码见：

。