Rust配置管理库config_struct的使用指南

config_struct是一个Rust库，用于自动化生成类型安全的配置结构体，并支持从环境变量和配置文件解析配置。

主要特性

• 自动生成类型安全的配置结构体
• 支持从环境变量加载配置
• 支持从JSON、TOML、YAML等配置文件加载
• 提供默认值支持
• 支持嵌套配置结构

安装

在Cargo.toml中添加依赖：

[dependencies]
config_struct = "0.5"
serde = { version = "1.0", features = ["derive"] }

基本使用方法

1. 定义配置模板

创建一个JSON文件作为配置模板，例如config_template.json：

{
    "server": {
        "host": "localhost",
        "port": 8080
    },
    "database": {
        "url": "postgres://user:pass@localhost/db",
        "pool_size": 5
    },
    "debug_mode": false
}

2. 生成Rust配置结构体

使用config_struct的构建脚本来自动生成配置结构体。在build.rs中添加：

use config_struct::{Error, StructOptions};

fn main() -> Result<(), Error> {
    config_struct::create_config(
        "config_template.json",
        "src/config.rs",
        &StructOptions {
            serde_support: true,
            ..Default::default()
        })?;

    Ok(())
}

3. 使用生成的配置结构体

生成的src/config.rs文件将包含类型安全的配置结构体。在你的代码中可以这样使用：

mod config;
use config::Config;

fn main() {
    // 从环境变量加载配置
    let config = Config::from_env().expect("Failed to load config from env");
    
    println!("Server running on {}:{}", config.server.host, config.server.port);
    println!("Database URL: {}", config.database.url);
    
    if config.debug_mode {
        println!("Debug mode enabled");
    }
}

完整示例demo

以下是使用config_struct的完整示例：

1. 项目结构

my_app/
├── Cargo.toml
├── build.rs
├── config_template.json
└── src/
    └── main.rs

1. Cargo.toml

[package]
name = "my_app"
version = "0.1.0"
edition = "2021"

[dependencies]
config_struct = "0.5"
serde = { version = "1.0", features = ["derive"] }

1. config_template.json

{
    "app": {
        "name": "MyApp",
        "version": "1.0.0"
    },
    "features": {
        "auth": true,
        "logging": false
    },
    "max_connections": 100
}

1. build.rs

use config_struct::{Error, StructOptions};

fn main() -> Result<(), Error> {
    config_struct::create_config(
        "config_template.json",
        "src/config.rs",
        &StructOptions {
            serde_support: true,
            generate_loaders: true,
            ..Default::default()
        })?;

    Ok(())
}

1. src/main.rs

mod config;
use config::Config;

fn main() {
    // 从环境变量加载配置
    let config = match Config::from_env() {
        Ok(c) => c,
        Err(e) => {
            eprintln!("Failed to load config from env: {}", e);
            // 从默认配置文件加载作为回退
            Config::from_json_file("config.json")
                .expect("Failed to load config from file")
        }
    };
    
    println!("Running {} v{}", config.app.name, config.app.version);
    
    if config.features.auth {
        println!("Authentication feature is enabled");
    }
    
    if config.features.logging {
        println!("Logging feature is enabled");
    }
    
    println!("Max connections: {}", config.max_connections);
    
    // 示例：使用环境变量覆盖配置
    println!("\nTry running with environment variables:");
    println!("export APP_NAME=\"MyApp2\"");
    println!("export FEATURES_AUTH=false");
    println!("export MAX_CONNECTIONS=200");
}

高级用法

从文件加载配置

use config::Config;

fn main() {
    // 从JSON文件加载
    let config = Config::from_json_file("config.json")
        .expect("Failed to load config from file");
    
    // 或者从TOML文件加载
    let config = Config::from_toml_file("config.toml")
        .expect("Failed to load config from file");
}

环境变量映射

默认情况下，config_struct会将字段名转换为大写加下划线的形式作为环境变量名：

• server.host → SERVER_HOST
• database.pool_size → DATABASE_POOL_SIZE

你可以通过环境变量来覆盖配置：

export SERVER_PORT=9090
export DATABASE_URL="postgres://newuser:newpass@remotehost/db"

自定义选项

在生成结构体时可以自定义各种选项：

StructOptions {
    serde_support: true,      // 启用serde支持
    generate_loaders: true,   // 生成from_env, from_file等方法
    env_prefix: "MYAPP_",     // 自定义环境变量前缀
    ..Default::default()
}

注意事项

1. 每次修改配置模板后需要重新运行构建（cargo build）以更新生成的Rust代码
2. 环境变量值需要能够解析为对应的Rust类型
3. 对于可选字段，可以在模板中使用null表示

config_struct通过自动化生成类型安全的配置结构体，大大简化了Rust应用程序的配置管理，同时保证了配置访问的类型安全性。