ZZ-Validator DSL 使用说明书

1. 简介

ZZ-Validator DSL 是一种轻量级的描述语言，用于定义 JSON/对象字段的类型、约束、默认值及可选性。
主要用途包括：

• 字段类型验证（string、int、float、bool、object、array 等）
• 约束规则（长度、范围、正则、枚举）
• 默认值填充与可选字段支持
• 嵌套对象与数组验证
• 支持扩展类型（email、uuid、uri 等）

2. 基本语法

字段定义格式：

<name>?:<type>[<constraints>] = <default>

各部分含义

• name：字段名
• ?：表示字段可选，不带?表示字段必须存在
• type：字段类型
• [constraints]：可选约束，如长度、范围、正则
• = <default>：可选默认值

3. 支持类型

3.1 基本类型

3.2 扩展类型

3.3 联合类型

可使用 | 定义多个可接受类型：

id: int|float

4. 约束规则

4.1 长度/范围

• 字符串长度限制：string[3,20]
• 数值范围限制：int[0,100] 或 float(0.0, 10.0)

4.2 正则表达式

username:string[3,20] regex("^[a-zA-Z0-9_]+$")

4.3 枚举值

role:string enum("admin","user","guest")

4.4 默认值

age:int[0,150]=30
active:bool=true

4.5 可选字段

在字段名后加 ?：

nickname?:string[0,20]
email?:email

5. 嵌套对象和数组

5.1 对象

profile:object(
    first_name:string[1,50],
    last_name:string[1,50],
    contact:object(
        email:email,
        phone?:string[0,20]
    )
)

5.2 数组

tags:array<string[1,10]>

6. 示例 DSL

(
    username:string[3,20] regex("^[a-zA-Z0-9_]+$"),
    age:int[0,150]=30,
    email?:email,
    id:uuid,
    homepage?:uri,
    profile:object(
        first_name:string[1,50],
        last_name:string[1,50],
        contact:object(
            email:email,
            phone?:string[0,20]
        )
    ),
    tags:array<string[1,10]>,
    distance:float[1.0,2.0]=1.5
)

7. 验证规则说明

• 默认值：当字段缺失且有默认值时自动填充
• 可选字段：字段缺失不会报错
• union types：值需匹配至少一个类型
• 嵌套对象/数组：递归验证所有子字段
• 正则与枚举：严格匹配指定模式或枚举值
• 范围约束：适用于 int、float 和 string（长度）类型

8. 扩展指南

• 增加自定义类型：
  • 如 mac_address、isbn、credit_card 等
  • 可通过正则或回调函数实现
• 扩展验证规则：
  • 自定义 constraint 类型
  • 嵌套对象可递归使用新类型

9. 注意事项

• 字符串长度用 usize 计算
• union types 验证顺序从左到右，匹配即停止
• 对象默认值需通过 Value::Object 插入
• 数组验证对每个元素执行规则