OptionalStruct

快速入门

从tests/builder.rs文件开始

use optional_struct::*;

#[optional_struct]
#[derive(Eq, PartialEq, Debug)]
struct Foo {
    paf: u16,
    bar: Option<u8>,
    #[optional_wrap]
    baz: Option<char>,
    #[optional_rename(OptionalMiaou)]
    #[optional_wrap]
    miaou: Miaou,
}

#[optional_struct]
#[derive(Eq, PartialEq, Debug)]
struct Miaou {
    a: i8,
    b: i16,
}

#[test]
fn test_builder() {
    let default = Foo {
        paf: 12,
        bar: None,
        baz: Some('a'),
        miaou: Miaou {
            a: 1,
            b: -1,
        },
    };

    let first = OptionalFoo {
        paf: Some(42),
        bar: Some(7),
        baz: Some(None),
        miaou: None,
    };

    let second = OptionalFoo {
        paf: Some(24),
        bar: None,
        baz: Some(Some('c')),
        miaou: Some(OptionalMiaou {
            a: Some(2),
            b: None,
        }),
    };

    let collapsed = first.apply(second).build(default);
    assert_eq!(collapsed, Foo {
        paf: 24,
        bar: Some(7),
        baz: Some('c'),
        miaou: Miaou { a: 2, b: -1 },
    });
}

目标

由于Rust没有默认参数，并且一些工具在反序列化数据时（例如serde）非常严格，缺失的配置值处理起来可能相当令人沮丧。例如

#[derive(Deserialize)]
struct Config {
    log_file: PathBuf,
}

如果我们从文件中读取配置，而log_file未指定，serde将无法创建结构体。虽然serde 提供了一些方法来为字段设置默认值，例如

#[derive(Deserialize)]
struct Config {
    #[serde(default = "get_next_log_filename")]
    log_file: PathBuf,
}

存在明显的局限性。此crate旨在通过允许可选值，并提供一种简单的方法来应用从不同来源获得的价值来构建我们的配置，从而填补这一空白。

使用optional_struct，可以定义所需配置，就像它将被使用一样，并仅使用生成的结构体来处理配置/缺失值/默认值。

如何

optional_struct宏生成一个包含与标记的结构体相同字段的结构体，但由Option包装。新结构体上的一个函数允许将值应用到原始结构体上（如果Option不是None）。这可以多次调用，以应用来自不同来源的配置，同时让调用者完全控制如何设置值，因为生成的结构体可以轻松操作和传递，在构建最终配置之前。

功能

1. 重命名生成的结构体

#[optional_struct(HeyU)]
struct Config();

fn main() {
    let me = HeyU();
}

2. 处理递归类型

#[optional_struct]
struct Foo {
    // Replaces Option<Bar> with OptionalBar
    // To generate Option<OptionalBar> instead, add an extra #[optional_wrap]
    // as described later
    #[optional_rename(OptionalBar)]
    bar: Bar,
}

3. 处理原始结构体中的Option（通过忽略它们）

#[optional_struct]
struct Foo {
    bar: Option<u8>,
}

fn main() {
    let opt_f = OptionalFoo { bar: Some(1) };
}

4. 强制包装（或不）字段

#[optional_struct]
struct Foo {
    #[optional_skip_wrap]
    bar: char,

    // Useless here since we wrap by default
    #[optional_wrap]
    baz: bool,
}

fn main() {
    let opt_f = OptionalFoo { bar: 'a', baz: Some(false) };
}

5. 更改默认包装行为

#[optional_struct(OptionalFoo, false)]
struct Foo {
    bar: u8,
    #[optional_wrap]
    baz: i8,
}

fn main() {
    let opt_f = OptionalFoo { bar: 1, baz: None };
}

6. 向生成的结构体添加serde的skip_serializing_if = "Option::is_none"属性

通过将属性#[optional_serde_skip_none]添加到字段中，生成的结构体将具有相同的字段标记#[serde(skip_serializing_if = "Option::is_none")]。此属性使serde在Option的值为none时完全跳过字段（而不是在序列化到json时保存例如"value" = null）。

apply、build和try_build

这三个函数用于通过合并“左侧”的值来构建结构的最终版本。

函数的签名（伪代码）

impl OptionalStruct {
    fn build(self, s: Struct) -> Struct;
    fn try_build(self) -> Result<Struct, OptionalStruct>;
    fn apply(self, other: OptionalStruct) -> OptionalStruct;
}

这些函数的作用

1. build接受一个实际的Struct并设置所有字段，基于哪些字段在OptionalStruct中被设置。缺失的字段保持不变。具有强制包装属性的Option字段将不会覆盖值，例如Some(1)不会覆盖Some(2)（请参阅初始示例以了解具体情境）。

2. try_build尝试从OptionalStruct构建整个Struct，如果一切顺利，则返回一个Ok(Struct)，如果缺少内容，则返回初始的Err(OptionalStruct)。

3. apply接受一个OptionalStruct作为参数，并将其字段应用于左侧（即self）。如果self和other都定义了某个值，则取other的值。如果self定义了某个值但other没有，则保留该值。当然，如果self没有定义某个值但other有，则使用该值。