Rust数据结构校验库 near-schema-checker-core 使用指南

简介

near-schema-checker-core 是一个用于 Rust 的高效数据结构校验库，专门为 NEAR 协议设计，但也可用于其他 Rust 项目中需要 schema 验证的场景。它提供了强大的类型检查和数据结构验证功能。

主要特性

• 高性能的 schema 验证
• 灵活的类型检查系统
• 支持复杂数据结构验证
• 可扩展的验证规则
• 友好的错误报告

安装

在 Cargo.toml 中添加依赖：

[dependencies]
near-schema-checker-core = "0.1.0"  # 请使用最新版本

基本使用方法

1. 定义 Schema

use near_schema_checker_core::{Schema, Type};

let schema = Schema::new()
    .field("name", Type::String)
    .field("age", Type::Number)
    .field("is_active", Type::Boolean)
    .field("tags", Type::Array(Box::new(Type::String)));

2. 验证数据结构

use near_schema_checker_core::validate;
use serde_json::json;

let data = json!({
    "name": "Alice",
    "age": 30,
    "is_active": true,
    "tags": ["rust", "blockchain"]
});

let result = validate(&schema, &data);
assert!(result.is_ok());

3. 处理验证错误

let invalid_data = json!({
    "name": "Bob",
    "age": "thirty",  // 应该是数字
    "is_active": true
});

match validate(&schema, &invalid_data) {
    Ok(_) => println!("数据有效"),
    Err(e) => println!("验证错误: {}", e),
}

高级用法

自定义验证规则

use near_schema_checker_core::{Validator, ValidationError};

struct AgeValidator;

impl Validator for AgeValidator {
    fn validate(&self, value: &serde_json::Value) -> Result<(), ValidationError> {
        if let Some(age) = value.as_i64() {
            if age >= 0 && age <= 120 {
                Ok(())
            } else {
                Err(ValidationError::new("年龄必须在0-120之间"))
            }
        } else {
            Err(ValidationError::new("年龄必须是数字"))
        }
    }
}

let schema = Schema::new()
    .field("age", Type::Custom(Box::new(AgeValidator)));

嵌套结构验证

let user_schema = Schema::new()
    .field("name", Type::String)
    .field("address", Schema::new()
        .field("street", Type::String)
        .field("city", Type::String)
        .field("zip", Type::Number)
    );

可选字段

let schema = Schema::new()
    .field("required_field", Type::String)
    .optional_field("optional_field", Type::Number);

性能建议

1. 重用 Schema 实例，避免重复构建
2. 对于复杂结构，考虑使用 lazy_static 或 once_cell 来存储 Schema
3. 在性能关键路径上，可以预先编译 Schema

错误处理最佳实践

use near_schema_checker_core::ValidationError;

fn process_data(data: &serde_json::Value) -> Result<(), String> {
    let result = validate(&schema, data);
    match result {
        Ok(_) => Ok(()),
        Err(e) => {
            // 收集所有验证错误
            let errors = e.collect_all_errors();
            Err(format!("发现{}个验证错误: {:?}", errors.len(), errors))
        }
    }
}

完整示例代码

use near_schema_checker_core::{Schema, Type, validate, Validator, ValidationError};
use serde_json::json;
use lazy_static::lazy_static;

// 自定义年龄验证器
struct CustomAgeValidator;

impl Validator for CustomAgeValidator {
    fn validate(&self, value: &serde_json::Value) -> Result<(), ValidationError> {
        if let Some(age) = value.as_i64() {
            if age >= 18 && age <= 100 {
                Ok(())
            } else {
                Err(ValidationError::new("年龄必须在18-100岁之间"))
            }
        } else {
            Err(ValidationError::new("年龄必须是数字"))
        }
    }
}

// 定义全局Schema
lazy_static! {
    static ref USER_SCHEMA: Schema = Schema::new()
        .field("id", Type::String)
        .field("username", Type::String)
        .field("email", Type::String)
        .field("age", Type::Custom(Box::new(CustomAgeValidator)))
        .field("address", Schema::new()
            .field("street", Type::String)
            .field("city", Type::String)
            .field("zip_code", Type::Number)
        )
        .optional_field("phone", Type::String);
}

fn validate_user_data(user_data: &serde_json::Value) -> Result<(), Vec<String>> {
    match validate(&USER_SCHEMA, user_data) {
        Ok(_) => Ok(()),
        Err(e) => {
            let errors = e.collect_all_errors()
                .into_iter()
                .map(|err| err.to_string())
                .collect();
            Err(errors)
        }
    }
}

fn main() {
    // 有效数据示例
    let valid_user = json!({
        "id": "user_001",
        "username": "rust_dev",
        "email": "dev@example.com",
        "age": 25,
        "address": {
            "street": "Main St",
            "city": "Techville",
            "zip_code": 12345
        },
        "phone": "+1234567890"
    });

    // 无效数据示例
    let invalid_user = json!({
        "id": "user_002",
        "username": "young_user",
        "email": "young@example.com",
        "age": 16,  // 不满足自定义验证规则
        "address": {
            "street": "Second St",
            "city": "Youngtown"
            // 缺少zip_code字段
        }
    });

    println!("验证有效用户数据:");
    match validate_user_data(&valid_user) {
        Ok(_) => println!("✅ 用户数据验证通过"),
        Err(e) => println!("❌ 验证错误: {:?}", e),
    }

    println!("\n验证无效用户数据:");
    match validate_user_data(&invalid_user) {
        Ok(_) => println!("✅ 用户数据验证通过"),
        Err(e) => println!("❌ 验证错误: {:?}", e),
    }
}

这个完整示例展示了如何使用 near-schema-checker-core 进行复杂的数据结构验证，包括：

1. 定义全局 Schema 并使用 lazy_static 优化性能
2. 实现自定义验证器
3. 处理嵌套结构
4. 使用可选字段
5. 详细的错误处理

near-schema-checker-core 提供了强大而灵活的数据验证功能，特别适合需要严格数据结构检查的 Rust 应用程序。