Rust结构体验证库superstruct的使用指南

介绍

superstruct是一个Rust库，专注于提供强类型的数据验证和结构体转换功能。它允许你定义数据结构的预期形状，然后验证输入数据是否符合该结构，并在验证过程中自动转换为强类型结构体。

主要特性：

• 声明式验证规则
• 自动错误收集
• 支持嵌套结构验证
• 类型安全的转换
• 友好的错误信息

安装

在Cargo.toml中添加依赖：

[dependencies]
superstruct = "0.6"

基本使用方法

1. 定义结构体

use superstruct::superstruct;

#[superstruct]
struct User {
    id: String,
    name: String,
    #[superstruct(only(V2))]
    email: String,
    age: u8,
}

2. 验证和转换

let data = serde_json::json!({
    "id": "123",
    "name": "Alice",
    "age": 25
});

let user = User::from_value(data).unwrap();
println!("User: {:?}", user);

进阶用法

版本化结构体

#[superstruct]
struct Message {
    text: String,
    #[superstruct(only(V2))]
    timestamp: i64,
    #[superstruct(only(V1))]
    is_read: bool,
}

// 使用V1版本
let v1_data = serde_json::json!({
    "text": "Hello",
    "is_read": true
});
let msg_v1 = Message::from_value(v1_data).unwrap();

// 使用V2版本
let v2_data = serde_json::json!({
    "text": "Hello",
    "timestamp": 1672531200
});
let msg_v2 = Message::from_value(v2_data).unwrap();

自定义验证

#[superstruct]
struct Product {
    id: String,
    #[superstruct(validator = "validate_price")]
    price: f64,
}

fn validate_price(price: &f64) -> Result<(), String> {
    if *price > 0.0 {
        Ok(())
    } else {
        Err("Price must be positive".to_string())
    }
}

错误处理

let invalid_data = serde_json::json!({
    "id": "123",
    "price": -10.0
});

match Product::from_value(invalid_data) {
    Ok(_) => println!("Valid product"),
    Err(e) => println!("Validation errors: {:?}", e),
}

实际示例

API请求验证

#[superstruct]
struct ApiRequest {
    #[superstruct(validator = "validate_api_key")]
    api_key: String,
    action: String,
    #[superstruct(only(PremiumRequest))]
    premium_feature: bool,
}

fn validate_api_key(key: &str) -> Result<(), String> {
    if key.starts_with("sk_") && key.len() == 32 {
        Ok(())
    } else {
        Err("Invalid API key format".to_string())
    }
}

// 使用
let request_data = serde_json::json!({
    "api_key": "sk_123456789012345678901234567890",
    "action": "create"
});

let request = ApiRequest::from_value(request_data).unwrap();

配置验证

#[superstruct]
struct AppConfig {
    #[superstruct(validator = "validate_port")]
    port: u16,
    db_url: String,
    #[superstruct(default = "false")]
    debug_mode: bool,
}

fn validate_port(port: &u16) -> Result<(), String> {
    if *port > 1024 {
        Ok(())
    } else {
        Err("Port must be greater than 1024".to_string())
    }
}

// 使用默认值
let config_data = serde_json::json!({
    "port": 8080,
    "db_url": "postgres://user:pass@localhost/db"
});

let config = AppConfig::from_value(config_data).unwrap();
assert_eq!(config.debug_mode(), false);

完整示例demo

下面是一个完整的示例，展示了如何使用superstruct进行用户注册数据的验证：

use superstruct::superstruct;
use serde_json;

// 定义用户结构体
#[superstruct]
struct UserRegistration {
    #[superstruct(validator = "validate_username")]
    username: String,
    #[superstruct(validator = "validate_email")]
    email: String,
    #[superstruct(validator = "validate_password")]
    password: String,
    #[superstruct(default = "false")]
    is_verified: bool,
}

// 用户名验证函数
fn validate_username(username: &str) -> Result<(), String> {
    if username.len() >= 3 && username.len() <= 20 {
        Ok(())
    } else {
        Err("Username must be between 3 and 20 characters".to_string())
    }
}

// 邮箱验证函数
fn validate_email(email: &str) -> Result<(), String> {
    if email.contains('@') && email.contains('.') {
        Ok(())
    } else {
        Err("Invalid email format".to_string())
    }
}

// 密码验证函数
fn validate_password(password: &str) -> Result<(), String> {
    if password.len() >= 8 {
        Ok(())
    } else {
        Err("Password must be at least 8 characters".to_string())
    }
}

fn main() {
    // 有效数据示例
    let valid_data = serde_json::json!({
        "username": "rustfan",
        "email": "user@example.com",
        "password": "secure123"
    });
    
    match UserRegistration::from_value(valid_data) {
        Ok(user) => {
            println!("Registration successful!");
            println!("Username: {}", user.username());
            println!("Email: {}", user.email());
            println!("Verified: {}", user.is_verified());
        }
        Err(e) => println!("Validation errors: {:?}", e),
    }

    // 无效数据示例
    let invalid_data = serde_json::json!({
        "username": "a",  // 太短
        "email": "invalid",  // 格式错误
        "password": "short"  // 太短
    });
    
    match UserRegistration::from_value(invalid_data) {
        Ok(_) => println!("This should not happen!"),
        Err(e) => {
            println!("Registration failed with errors:");
            for error in e {
                println!("- {}", error);
            }
        }
    }
}

这个完整示例展示了：

1. 定义带有验证规则的结构体
2. 实现自定义验证函数
3. 使用默认值
4. 处理验证成功和失败的情况
5. 输出友好的错误信息

superstruct通过提供类型安全的验证和转换，可以帮助你在Rust应用中构建更健壮的数据处理流程，特别是在处理外部输入（如API请求、配置文件等）时非常有用。