Confgr

概述

Config推导宏通过以下顺序自动从源中加载设置，简化了应用程序配置

1. 环境变量.
2. 配置文件（例如，toml，json，yaml，ini，ron，json5）。
3. 默认值.

主要功能

• 简洁性：最少的样板代码。定义您的配置结构体，自定义宏，然后即可使用。
• 灵活性：支持多种配置文件格式，包括toml，json，yaml，ini，ron和json5。
• 集成：与其他crate（如smart_default）协同工作。

还有一些有用的辅助属性可以自定义推导宏的行为。

路径属性行为

• env_path：将提供的环境变量解析为配置文件路径。这优先于 path 和 default_path，但如果文件或环境不存在，则不会引发恐慌。
• path：直接设置配置文件的路径。当设置后，不能使用 default_path。如果文件不存在，则引发恐慌。
• default_path：与 path 相同，但如果文件不存在，则不会引发恐慌。

用法

serde 是必需的依赖项。

 [dependencies]
 confgr = "0.2.0"
 serde = { version = "1.0", features = ["derive"] }

然后按如下方式定义您的配置

use confgr::prelude::*;

#[derive(Config)]
#[config(path = "docs.toml", prefix = "APP")]
pub struct AppConfig {
  port: u32,
  address: String,
  #[config(key = "DEBUG_MODE")]
  debug: bool,
}

// Default implementation is required.
impl Default for AppConfig {
  fn default() -> Self {
    Self {
      port: 3000,
      address: "127.0.0.1".to_string(),
      debug: false
    }
  }
}

std::env::set_var("APP_PORT", "4000");
std::env::set_var("DEBUG_MODE", "true");

let settings = AppConfig::load_config();

assert_eq!(settings.port, 4000);
assert_eq!(settings.address, "127.0.0.1");
assert!(settings.debug)

查看 示例目录 以获取更多信息。

警告/陷阱

• 嵌套结构体不会根据其自己的 path 属性加载单独的文件。如果您想加载多个文件，必须使用多个结构体并调用多个 load_config() 调用。这可能在未来的版本中发生变化。
• 未实现 FromStr 的类型必须使用 #[config(skip)] 或 #[config(nest)]。
• separator 字符仅在前缀和字段名称之间插入，不会在任何解析的字段名称部分插入。
• prefix 按字段或整个结构体应用，但如果使用 #[config(key = "_")]，则会被忽略。
• 所有配置结构体必须实现 Default。
• 在配置结构体字段中使用的自定义类型必须实现 Deserialize、Clone 和 Debug。
• Option 目前与在实现 Confgr 的类型上使用 #[config)nest)] 不兼容。

调试

在遇到宏使用问题时，以下方法可能有所帮助。

验证环境变量

可以使用 get_env_keys() 方法检索由 derive 宏构建的环境变量键名。

use std::collections::HashMap;
use confgr::prelude::*;

#[derive(Config, Default)]
#[config(prefix = "APP")]
pub struct AppConfig {
    port: u32,
    #[config(separator = "__")]
    address: String,
    #[config(key = "DEBUG_MODE")]
    debug: bool,
}

let keys: HashMap<String, String> = AppConfig::get_env_keys();

assert_eq!(keys["port"], "APP_PORT");
assert_eq!(keys["address"], "APP__ADDRESS");
assert_eq!(keys["debug"], "DEBUG_MODE");

验证配置文件路径

您可以使用 check_file() 来确保配置文件可通过提供的 path、path_env 或 default_path 属性访问。

use confgr::prelude::*;

#[derive(Config, Default)]
#[config(path = "docs.toml", env_path = "APP_CONFIG_FILE")]
pub struct AppConfig {
    port: u32,
    debug: bool,
}

std::env::set_var("APP_CONFIG_FILE", "env_config.toml");
AppConfig::check_file().expect("Failed to open configuration file.");

std::env::remove_var("APP_CONFIG_FILE");
AppConfig::check_file().expect("Failed to open configuration file.");

测试反序列化

可以使用 deserialize_from_file() 方法手动测试配置反序列化步骤。返回一个 Result<Self::Layer, ConfgrError>。

use confgr::prelude::\*;

#[derive(Config, Default)] #[config(path = "docs.toml")]
pub struct AppConfig {
port: u32,
debug: bool,
}

let config = AppConfig::deserialize_from_file().expect("Failed to deserialize configuration.");
println!("Deserialized configuration: {:?}", config);

注意事项

• 版本不稳定性：目前，此包处于不稳定开发阶段，我保留在未来版本中进行破坏性更改的权利，无需承担向后兼容性的义务。
• 生产使用注意事项：这是我的第一个公开的 Rust 包，虽然它功能齐全且对我很有用，但在需要稳定性和性能保证的关键生产环境中，强烈建议不要过度依赖此库，除非经过彻底测试。
• 贡献：欢迎贡献！无论是功能请求、错误报告还是拉取请求，我都非常欢迎一些建设性的反馈！

我强烈推荐查看 config 包，因为它是一个功能齐全的非-proc-macro 替代品。此包实际上依赖于 config 进行文件解析。