Golang 运行时值解析与验证库 ZogZod 使用指南

ZogZod 是一个受 TypeScript 的 Zod 库启发的 Golang 运行时值解析与验证库，它提供了简洁的 API 来定义数据模式并进行验证。

安装

go get github.com/go-zoz/zog

基本用法

1. 定义模式

import "github.com/go-zoz/zog"

// 定义一个用户模式
userSchema := zog.Object{
    "name": zog.String().Min(3).Max(50),
    "age": zog.Number().Min(18).Max(120),
    "email": zog.String().Email(),
    "isAdmin": zog.Boolean().Optional(),
    "address": zog.Object{
        "street": zog.String(),
        "city": zog.String(),
    },
}

2. 解析和验证数据

data := map[string]interface{}{
    "name": "John Doe",
    "age": 30,
    "email": "john@example.com",
    "address": map[string]interface{}{
        "street": "123 Main St",
        "city": "New York",
    },
}

result, err := userSchema.Parse(data)
if err != nil {
    // 处理验证错误
    fmt.Println("Validation error:", err)
    return
}

// 使用解析后的数据
fmt.Printf("Valid user: %+v\n", result)

高级特性

1. 自定义验证器

passwordSchema := zog.String().
    Min(8).
    Max(50).
    Regex(`[A-Z]`, "must contain at least one uppercase letter").
    Regex(`[0-9]`, "must contain at least one number")

// 使用
_, err := passwordSchema.Parse("weakpassword")
if err != nil {
    fmt.Println(err) // 会显示自定义错误消息
}

2. 转换数据

// 定义一个转换器，将字符串转换为整数
toIntSchema := zog.String().Transform(func(s string) (interface{}, error) {
    return strconv.Atoi(s)
})

value, _ := toIntSchema.Parse("42")
fmt.Printf("%T %v\n", value, value) // int 42

3. 联合类型

idSchema := zog.Union(
    zog.String().UUID(),
    zog.Number().Int(),
)

_, err1 := idSchema.Parse("550e8400-e29b-41d4-a716-446655440000") // UUID
_, err2 := idSchema.Parse(12345) // 数字

4. 数组验证

tagsSchema := zog.Array(zog.String().Min(2).Max(20)).Max(5)

_, err := tagsSchema.Parse([]string{"go", "programming", "backend"})
if err != nil {
    fmt.Println(err)
}

5. 异步验证

// 定义一个异步验证器，检查用户名是否唯一
usernameSchema := zog.String().
    Min(3).
    Max(20).
    Async(func(s string) error {
        // 模拟异步检查
        time.Sleep(100 * time.Millisecond)
        if s == "takenusername" {
            return fmt.Errorf("username already taken")
        }
        return nil
    })

err := usernameSchema.ParseAsync("takenusername").Await()
if err != nil {
    fmt.Println(err)
}

错误处理

ZogZod 提供了详细的错误信息：

_, err := userSchema.Parse(map[string]interface{}{
    "name": "Jo", // 太短
    "age": 17,    // 小于18
    "email": "invalid",
})

if err != nil {
    if validationErr, ok := err.(zog.ValidationError); ok {
        for _, issue := range validationErr.Issues {
            fmt.Printf("Field %s: %s (code: %s)\n", 
                issue.Path, issue.Message, issue.Code)
        }
    }
}

性能考虑

ZogZod 在设计时考虑了性能：

1. 模式定义是静态的，可以重复使用
2. 验证过程是惰性的，只在调用 Parse 时执行
3. 提供了预编译模式选项

// 预编译模式以提高性能
compiledSchema, err := userSchema.Compile()
if err != nil {
    panic(err)
}

// 使用编译后的模式
result, err := compiledSchema.Parse(data)

总结

ZogZod 为 Golang 提供了强大的运行时值解析和验证能力，主要特点包括：

• 直观的链式 API
• 丰富的内置验证器
• 详细的错误报告
• 类型安全的解析结果
• 支持自定义验证规则
• 异步验证支持

对于需要处理复杂输入验证的 Golang 应用，ZogZod 是一个值得考虑的选择。