go-ozzo/ozzo-validation 版本升级指南：从 2.x 到 4.x 的迁移要点-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00539/article/details/148551767

go-ozzo/ozzo-validation 版本升级指南：从 2.x 到 4.x 的迁移要点

ozzo-validation An idiomatic Go (golang) validation package. Supports configurable and extensible validation rules (validators) using normal language constructs instead of error-prone struct tags. 项目地址: https://gitcode.com/gh_mirrors/oz/ozzo-validation

前言

go-ozzo/ozzo-validation 是一个功能强大的 Go 语言数据验证库，随着版本的迭代，其 API 设计和功能实现也在不断优化。本文将为开发者详细解析从 2.x 升级到 4.x 版本的关键变化点，帮助您顺利完成迁移工作。

从 3.x 升级到 4.x 的注意事项

错误消息模板语法变更

在 4.x 版本中，内置验证规则的错误消息模板语法进行了重大改进，从传统的 %v 格式化占位符变更为更灵活的 Go 模板变量语法。这一变化主要影响以下验证规则：

Length 规则：
- 旧版：使用 %v 表示最小和最大长度
- 新版：使用 {{.min}} 和 {{.max}} 模板变量
Min 规则：
- 旧版：%v 表示下限值
- 新版：{{.threshold}} 模板变量
Max 规则：
- 旧版：%v 表示上限值
- 新版：{{.threshold}} 模板变量
MultipleOf 规则：
- 旧版：%v 表示基数
- 新版：{{.base}} 模板变量

代码示例对比

// 3.x 版本写法
rule := validation.Length(2, 10).Error("长度必须在 %v 和 %v 之间")

// 4.x 版本写法
rule := validation.Length(2, 10).Error("长度必须在 {{.min}} 和 {{.max}} 之间")

这一变更使得错误消息的定制更加灵活，开发者可以在模板中使用更复杂的逻辑，同时也提高了代码的可读性。

从 2.x 升级到 3.x 的注意事项

1. 结构体验证方式重构

3.x 版本对结构体验证 API 进行了重新设计，移除了 StructRules 类型，改为更直观的 ValidateStruct 函数。

新旧对比示例

// 2.x 版本结构体验证
err := validation.StructRules{}.
    Add("Street", validation.Required, validation.Length(5, 50)).
    Add("City", validation.Required, validation.Length(5, 50)).
    Validate(address)

// 3.x 版本结构体验证
err := validation.ValidateStruct(&address,
    validation.Field(&address.Street, validation.Required, validation.Length(5, 50)),
    validation.Field(&address.City, validation.Required, validation.Length(5, 50)),
)

新 API 的优势：

直接使用结构体字段指针，减少字符串硬编码
代码更加类型安全
验证规则与字段直接关联，可读性更好

2. 简单值验证方式优化

对于非结构体类型的值验证，3.x 版本简化了验证流程，不再需要显式创建 Rules 对象。

代码示例对比

value := "example"

// 2.x 版本简单值验证
rules := validation.Rules{
    validation.Required,
    validation.Length(5, 100),
}
err := rules.Validate(value)

// 3.x 版本简单值验证
err := validation.Validate(value,
    validation.Required,
    validation.Length(5, 100),
)