只需看看数据的类型，想想它成功需要发生什么，就很容易记住它的含义。如果我们看不到任何（前缀）子结构的字段出现，那么我们就返回 None。如果我们看到其中一些出现，这表明我们应该产生一个 Some。一旦我们决定要产生 Some，如果我们在正常（非可选）方式下无法在 flatten 结构中做到这一点，则是一个错误。

one_of_fields

conf 提供了一种简单的方法来指定结构中的一些字段是互斥的。

#[derive(Conf)]
#[conf(at_most_one_of_fields(a, b, c))]
pub struct FooConfig {
    #[conf(short, long)]
    pub a: bool,
    #[conf(short, long)]
    pub b: Option<String>,
    #[conf(long, env)]
    pub c: Vec<String>,
}

当与两个字段一起使用时，它提供了在 clap-derive API 中使用 conflicts_with 的许多用法的翻译方式。

当与结构中的所有字段一起使用时，它类似于在 clap-derive API 中具有 multiple=false 和 required=false 的 ArgGroup。

这也与 flatten-optional 功能一起工作，因此可以在这个结构中将一个或多个可选扁平化组彼此或与简单参数互斥。

但是，它只能用于标记有此属性的结构的字段，不能用于扁平化结构内部的字段或结构中的其他地方。

conf 提供了一种需要 恰好 出现一个字段的变化。

#[derive(Conf)]
#[conf(one_of_fields(a, b, c))]
pub struct FooConfig {
    #[conf(short, long)]
    pub a: bool,
    #[conf(short, long)]
    pub b: Option<String>,
    #[conf(long, env)]
    pub c: Vec<String>,
}

当与结构中的所有字段一起使用时，这类似于在 clap-derive API 中具有 multiple=false 和 required=true 的 ArgGroup。

最后，conf 提供了另一种变化

#[derive(Conf)]
#[conf(at_least_one_of_fields(a, b, c))]
pub struct FooConfig {
    #[conf(short, long)]
    pub a: bool,
    #[conf(short, long)]
    pub b: Option<String>,
    #[conf(long, env)]
    pub c: Vec<String>,
}

当与结构中的所有字段一起使用时，这类似于在 clap-derive API 中具有 multiple=true 和 required=true 的 ArgGroup。

这些属性中的任何一个都可以在同一个结构上多次使用，以创建应用于该结构的多重约束。

验证谓词

flatten-optional 和 one_of_fields 提供了一些易于理解的方法来在 conf 结构中创建不同可选字段之间的依赖性和排他性约束。它们可以直接翻译许多简单的 ArgGroup 使用和 clap-derive API 中的某些约束。但是，clap 支持的许多其他约束类型不能直接转换为这种形式，并且我们不支持在字段上直接声明 arg group 成员关系，这是 clap 支持的。

同时，还有其他类型的约束，您可能有合法的使用需求，但在 clap 的 API 中无法表达。例如，您的某个参数可能是一个 Url 对象，您可能希望如果 Url 以 https 开头，则需要其他一些选项。据我所知，在 clap 中没有做这件事的方法。

与为 clap 的约束 API 中的每个函数提供直接类似物不同，conf 支持在每结构的基础上定义用户定义的验证谓词。

验证谓词是一个函数，它接受类型为 &T 的参数，其中 T 是当前的结构体，并返回 Result<(), impl Display>。

其行为与 value_parser 类似，任何函数表达式都可以接受。

这里的想法是，与其向 conf 中添加越来越多的单次约束类型，或者使用 proc-macro 属性来启用你编写非局部约束，不如你用 Rust 代码表达你想要的内容，一旦你的约束变得足够复杂。这样对你和 conf 来说都更容易维护。对于你来说，需要学习和记住的 API 更少，对于 conf 来说，需要测试和维护的 API 表面积也更小。当复杂的约束失败时，你还能生成非常精确的错误信息。

结合使用这些特性，你可以表达任何想要施加在配置结构体上的约束，并希望让它看起来更加自然。

鉴于对 T 的 validation_predicate 在实际解析 T 之后运行，为什么还要有这个特性呢？用户可以在 Config::parse 成功后自行运行这些函数。

使用 validation_predicate 的好处是，如果谓词失败，conf 仍然能够报告这些错误以及树中其他地方发生的任何错误。

例如，在这个配置结构体中

#[derive(Conf)]
pub struct Config {
    #[conf(flatten, prefix="auth")]
    pub auth_service: HttpClientConfig,

    #[conf(flatten, prefix="friend")]
    pub friend_service: HttpClientConfig,

    #[conf(flatten, prefix="snaps")]
    pub snaps_service: Option<HttpClientConfig>,
}

在解析 Config 时，可能会出现 auth_service 解析失败，因为缺少必要的参数，friend_service 解析失败，因为缺少参数和无效值，以及 snaps_service 解析成功但验证谓词失败。在这种情况下，conf 将报告所有这些错误，这与其他同类 crate 相区分。

谁应该使用这个包？

使用这个 crate 的最佳理由是，如果你有一个中型到大型项目，例如一个由多个服务组成的 Web 应用程序，它有大量的配置需求。你有多个服务，这些服务有几个共同的子系统或组件，这些组件有子组件，其中一些是共享的等，所有这些都应该按照 12 因素风格从环境中读取配置，并且可能需要紧急读取更多此类配置。你可能已经使用过 clap-derive，但随着项目的增长，你已经遇到了限制。

该 crate 的目的是帮助您以最简单、最易于维护的方式安排所有配置，同时确保在程序启动时检查所有需要的值（快速失败），在您的部署出现问题时，以最有帮助的方式报告尽可能多的配置错误，并提供正在读取的所有配置的自动化 --help 文档。

如果您认为这个 crate 很适合您，建议的使用方法是

• 每当您有一个您认为应该使用启动时读取的值的组件时，您应该为该组件创建一个配置结构体。您应该在结构体上 derive(Conf)，并在初始化时将配置结构体传递给组件。该配置结构体应与其配置的组件位于同一模块中。
• 如果您的组件由更大的组件初始化，那么该组件应具有自己的配置结构体，并且您应使用 flatten 来组装它。在展平时，通常应使用 prefix 和 help_prefix 选项。
• 每个二进制目标都应该有一个配置结构体，并且应该在 fn main 中 () 中 ::parse() 它。

这样，无论将来您发现需要为您的某个小组件添加更多配置值，您只需将其添加到相关的配置结构体中，它就会自动出现在需要它的每个服务中，需要多少次就出现多少次，并带有适当的命名前缀，而无需您在每一步都进行连接。此外，这还使得创建任何未来服务或工具的正确配置变得更加容易。它还使所有服务和工具都具有相似、可预测的风格，并将它们的所有配置文档化在 --help 中，即使是相当隐蔽的环境变量等，通常如果您直接从 std::env 读取它们，通常不会进行文档化。

何时应优先使用 clap-derive 而不是此软件包？

此软件包相对于 clap-derive 定义得有所不同，具有不同的功能和目标。

• clap-derive 旨在作为 clap 构建器 API 的替代方案，并暴露了构建器的基本所有功能。
• clap 本身主要是 CLI 参数解析器 （根据维护者所说），并且许多关于 env 支持的简单功能，如只能从 env 读取的参数，都被认为是范围之外的。

conf 对特性的强调有所不同。

• env 实际上是 12 因素 Web 应用程序最重要的东西。
• conf 拥有不同的架构，这使得在运行时在 struct 和将其展平的 struct 之间传递信息更加容易。这使它能够带来许多新的特性。许多细节尚未记录，也不属于公共 API 的一部分，这样它们就可以在不进行破坏性更改的情况下进行扩展和改进。
• conf 围绕错误报告有非常具体的目标。我们希望一次返回尽可能多的配置错误，因为部署可能需要相对较长的时间。

为了实现其目标，conf 实际上根本不使用 clap 来处理 env。clap 仅用于将 CLI 参数作为字符串解析，并渲染帮助文本，这是它最擅长做的两件事。

此软件包可以公开底层 clap 构建器的更多功能，并更接近 clap-derive 提供的功能集，但它可能永远不会公开所有这些功能 - 我们只能公开那些我们确信将很好地与我们所创建的附加功能（如 flatten-with-prefix）一起工作的功能，并且将很好地与底层 clap 构建器的使用方式一起工作。最有趣的功能是可以由常见的 Web 开发需求推动的功能。

如果您有非常特定的命令行界面参数解析需求，或者需要像素级精确的帮助文本，那么直接使用 clap 而不是这个crate会更好，因为这样您将拥有更多的控制权。 clap 是最成熟且功能最全面的命令行界面参数解析器，远远领先于其他。

在许多网络项目中，您并不真正有这样的需求。您并没有对 clap 进行非常复杂的使用，您的项目很小，您也不特别需要 conf 的任何功能，因此您可以使用 clap-derive 或 conf 一样好，并且几乎感觉不到任何差异。

如果您愿意，您可以坚持使用 clap-derive，然后只有在您发现需要 flatten-with-prefix 或其他功能时，再尝试切换到 conf。

conf 是为了使此类项目的迁移相对容易而设计的。（实际上，我开始开发 conf 是因为我有几个基于 clap-derive 的大型项目，我遇到了限制并被迫寻找我不满意的解决方案，而且我没有找到完全令人满意的替代方案。）如果您在尝试迁移时遇到困难，您可以发起讨论，我们可以尝试帮助您。

许可证

代码可供您选择在 MIT 或 Apache 2 许可下使用。