Converge

使用少量代码的Rust应用程序分层配置系统。通过仅合并配置，配置源及其合并方式的灵活性由用户控制。

简介

用户期望具有命令行参数、环境和配置文件分层配置的应用程序。此库允许以最少的努力和代码将这些来源分层。

动机

Unix哲学和微服务理念都导致了大量应用程序的编写。可以合理地预期这些应用程序将从命令行参数、环境和通常的配置文件中获取配置。随着应用程序的成熟，配置选项的数量往往会增加。管理这些配置的简单方法重复且容易出错，而为这添加测试会增加重复性。

关于

此库允许用户自行决定配置文件格式、命令行解析方法，并具有最小依赖。它与作为字段的配置项的结构的结构一起工作。这些结构必须实现一个具有单个方法的特性，该方法对于大多数结构通常是可派生的。

此方法与不可变数据结构一起工作，代码量非常少，但代价是在分层过程中克隆配置。这是一个合理的折衷方案，因为它通常只在应用程序的生命周期中发生一次。

快速入门

它基于一个名为 Converge 的特性，该特性有一个名为 converge 的单个方法，该方法位于 converge 包中。

pub trait Converge<Rhs = Self> {
    fn converge(self, default: Rhs) -> Self;
}

此特性可以使用 converge_derive 派生，如下所示。

#[derive(Converge)]
pub struct Config {
    pub config_file: Option<String>,
    pub loglevel: Option<i8>,
    pub xunit_local_globs: Option<Vec<String>>,
    pub environment_sk: Option<String>,
    pub environment_keys: Option<Vec<String>>,
    pub project_sk: Option<String>,
    pub project_identifier: Option<String>,
    pub project_human_name: Option<String>,
    pub run_identifier: Option<String>,
    pub run_sk: Option<String>,
    pub service_url: Option<String>,
}

可以从这些结构中填充嵌套的结构，然后可以将它们耦合在一起以派生具有清晰和简单先验的新实例。

let config_commandline : Config = parse_commandline_to_config();
let config_file : Config = parse_file_to_config();
let config_env : Config = parse_env_to_config();
let cfg = config_commandline.converge(config_file).converge(config_env);

可以存在非可选值的T类型字段，但这种情况不常见，因为在这种情况下，converge 只会取左侧的值。

设计您的配置结构

实现特性 Converge 的结构应包含一个逻辑分组字段，以表示您可能希望作为分层配置一部分使用的每个设置。

嵌套 Converge 结构的示例

#[derive(Converge)]
pub struct ConfigRabbitMqCredentials {
    pub username: Option<String>,
    pub password: Option<String>,
}

#[derive(Converge)]
pub struct ConfigRabbitMQ {
    pub host: Option<String>,
    pub port: Option<i32>,
    #[converge(nest)]
    pub credentials: Option<ConfigRabbitMqCredentials>,
}

当使用也实现 Converge 的字段类型时，可以使用 #[converge(nest)] 属性来标记字段也支持 Converge，这样就可以通过 converge 在此结构上使用 converge。

使用自定义字段收敛策略进行推导

#[derive(Converge)]
pub struct ConfigRabbitMqCredentials {
    pub username: Option<String>,
    pub password: Option<String>,
}

#[derive(Converge)]
pub struct ConfigRabbitMQ {
    pub host: Option<String>,
    pub port: Option<i32>,
    #[converge(strategy = converge::strategies::vec::replace_empty)]
    pub credentials: Vec<ConfigRabbitMqCredentials>,
}

字段也可以使用自定义收敛策略进行标记。其中策略是函数的路径，形式如下：

fn custom_function<T>(lhs: T, rhs: T) -> T

其中 T 与字段的类型相匹配。 converge crate 包含了一些按容器类型排序的通用泛型策略。

如何集成数据源

此库预计将与其他库结合使用，以解析配置文件格式、命令行和执行环境变量。在实际应用中，这些库呈现的结果结构通常与输入源紧密相关。 Converge trait 要求每个源提供一种常见的数据结构。通过为您常见的数据格式实现 From trait 或 TryFrom trait，Converge 可以应用于这些数据源。

相关库

以下是我们推荐提供配置数据的非详尽的数据源库列表。

• 解析应用程序命令行
  • clap
  • StructOpt
• 解析配置文件
  • toml
  • serde_yaml
  • serde_json
  • serde_xml_rs
• 解析环境变量
  • envy
  • envconfig

替代方案

以下是非详尽的可能替代方案列表。

• merge
  • 与 converge 有类似的想法。
• twelf
  • 适用于 Rust 的配置解决方案，包括 12-Factor 支持。