Rust配置管理库schematic_types使用指南

schematic_types是一个用于Rust的类型安全配置解析与验证库，它提供了一种声明式的方式来定义和验证配置结构。

主要特性

• 类型安全的配置解析
• 支持嵌套配置结构
• 内置多种验证器
• 支持环境变量注入
• 支持多种配置格式(JSON, YAML等)

基本使用方法

1. 添加依赖

首先在Cargo.toml中添加依赖：

[dependencies]
schematic_types = "0.3"
serde = { version = "1.0", features = ["derive"] }

2. 定义配置结构

use schematic_types::*;
use serde::{Deserialize, Serialize};

// 应用配置结构
#[derive(Config, Serialize, Deserialize)]
struct AppConfig {
    #[setting(
        default = "localhost",  // 默认值
        validate = "schematic_types::validate::hostname"  // 使用内置主机名验证器
    )]
    host: String,
    
    #[setting(default = 8080, validate = "schematic_types::validate::port")]  // 端口验证
    port: u16,
    
    #[setting(default = true)]  // 布尔值默认值
    debug: bool,
    
    #[setting(nested)]  // 嵌套配置
    database: DatabaseConfig,
}

// 数据库配置子结构
#[derive(Config, Serialize, Deserialize)]
struct DatabaseConfig {
    #[setting(default = "postgres://user:pass@localhost/db")]  // 数据库连接字符串默认值
    url: String,
    
    #[setting(default = 5)]  // 连接池大小默认值
    pool_size: u32,
}

3. 加载和验证配置

use schematic_types::ConfigLoader;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 从文件加载配置
    let config = ConfigLoader::<AppConfig>::new()
        .file("config.yaml")?  // 加载YAML配置文件
        .load()?;  // 解析并验证
    
    println!("Server will run on {}:{}", config.host, config.port);
    
    // 或者从环境变量加载配置
    let config = ConfigLoader::<AppConfig>::new()
        .env()  // 从环境变量加载
        .load()?;
    
    Ok(())
}

高级功能

自定义验证器

#[derive(Config, Serialize, Deserialize)]
struct CustomConfig {
    #[setting(validate = "validate_api_key")]  // 使用自定义验证函数
    api_key: String,
}

// 自定义API密钥验证函数
fn validate_api_key(key: &str) -> Result<(), String> {
    if key.len() != 32 {
        Err("API key must be 32 characters long".into())
    } else {
        Ok(())
    }
}

环境变量覆盖

#[derive(Config, Serialize, Deserialize)]
struct EnvConfig {
    #[setting(env = "APP_HOST")]  // 从APP_HOST环境变量读取
    host: String,
    
    #[setting(env = "APP_PORT")]  // 从APP_PORT环境变量读取
    port: u16,
}

合并多个配置源

let config = ConfigLoader::<AppConfig>::new()
    .file("config.yaml")?  // 基础配置
    .file("config.local.yaml")?  // 本地覆盖配置
    .env()?  // 环境变量最高优先级
    .load()?;

示例配置文件

config.yaml示例：

host: "0.0.0.0"
port: 3000
debug: false
database:
  url: "postgres://user:pass@prod-db/db"
  pool_size: 10

完整示例Demo

下面是一个完整的示例，展示如何使用schematic_types从多个源加载和验证配置：

use schematic_types::*;
use serde::{Deserialize, Serialize};

// 1. 定义配置结构
#[derive(Config, Serialize, Deserialize, Debug)]
struct AppConfig {
    #[setting(
        default = "localhost",
        validate = "schematic_types::validate::hostname"
    )]
    host: String,
    
    #[setting(default = 8080, validate = "schematic_types::validate::port")]
    port: u16,
    
    #[setting(default = true)]
    debug: bool,
    
    #[setting(nested)]
    database: DatabaseConfig,
}

#[derive(Config, Serialize, Deserialize, Debug)]
struct DatabaseConfig {
    #[setting(default = "postgres://user:pass@localhost/db")]
    url: String,
    
    #[setting(default = 5)]
    pool_size: u32,
}

// 2. 自定义验证器示例
#[derive(Config, Serialize, Deserialize, Debug)]
struct CustomConfig {
    #[setting(validate = "validate_api_key")]
    api_key: String,
}

fn validate_api_key(key: &str) -> Result<(), String> {
    if key.len() != 32 {
        Err("API key must be 32 characters long".into())
    } else {
        Ok(())
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 3. 从文件加载配置
    let config = ConfigLoader::<AppConfig>::new()
        .file("config.yaml")?
        .load()?;
    
    println!("Loaded config: {:?}", config);
    
    // 4. 从环境变量加载配置
    std::env::set_var("APP_HOST", "127.0.0.1");
    std::env::set_var("APP_PORT", "8081");
    
    let env_config = ConfigLoader::<AppConfig>::new()
        .env()
        .load()?;
    
    println!("Env config: {:?}", env_config);
    
    // 5. 合并多个配置源
    let merged_config = ConfigLoader::<AppConfig>::new()
        .file("config.yaml")?
        .env()?
        .load()?;
    
    println!("Merged config: {:?}", merged_config);
    
    Ok(())
}

schematic_types通过强大的类型系统和验证机制，可以帮助开发者构建更加健壮的配置处理逻辑，减少运行时配置错误。