Rust宏（proc-macro）库partially_derive的使用：实现部分派生（derive）功能的自定义过程宏扩展

简介

partially提供了一个可配置的派生宏，它会生成另一个结构体，其中所有字段都包装在Option<T>中，并实现Partial特性以允许将有值的字段有条件地应用到基础结构体。

partially_derive（或启用derive特性的partially）支持自动生成每个字段都包装在Option<T>中的镜像结构体，并生成一个Partial实现，允许将镜像结构体中的Some字段应用到基础结构体。

使用示例

使用派生宏

// `partially`安装时启用`derive`特性
use partially::Partial;

// 定义一个基础结构体，并使用`Partial`派生宏
#[derive(Partial)]
// 进一步指示宏在生成的结构体上派生`Default`
#[partially(derive(Default))]
struct Data {
    // 由于没有指定字段选项，这个字段将被映射到生成结构体中的`Option<String>`
    value: String,
}

// 示例用法
fn main() {
    // 由于我们为生成的结构体派生了Default，我们可以使用它来获取一个填充了`None`的部分结构体
    let empty_partial = PartialData::default();

    // 当然，我们也可以自己指定值
    let full_partial = PartialData {
        value: Some("modified".to_string()),
    };

    // 定义一个我们将操作的"基础"结构体
    let mut full = Data {
        value: "initial".to_string(),
    };

    // 应用空的部分结构体（注意返回`false`，表示没有应用任何内容）
    assert!(!full.apply_some(empty_partial));

    // 注意应用空部分结构体没有效果
    assert_eq!(full.value, "initial".to_string());

    // 应用完整部分结构体（注意返回`true`，表示应用了某些内容）
    assert!(full.apply_some(full_partial));

    // 注意应用完整部分结构体修改了值
    assert_eq!(full.value, "modified".to_string());
}

不使用派生宏

use partially::Partial;

struct Base {
    value: String,
}

#[derive(Default)]
struct PartialBase {
    value: Option<String>,
}

impl Partial for Base {
    type Item = PartialBase;

    #[allow(clippy::useless_conversion)]
    fn apply_some(&mut self, partial: Self::Item) -> bool {
        let will_apply_some = partial.value.is_some();

        if let Some(value) = partial.value {
            self.value = value.into();
        }

        will_apply_some
    }
}

fn main() {
    let empty_partial = PartialBase::default();
    let full_partial = PartialBase {
        value: Some("modified".to_string()),
    };

    let mut data = Base {
        value: "initial".to_string(),
    };

    assert!(!data.apply_some(empty_partial));

    assert_eq!(data.value, "initial".to_string());

    assert!(data.apply_some(full_partial));

    assert_eq!(data.value, "modified".to_string())
}

结构体选项

derive

用法示例：#[partially(derive(Debug, Default))]

指示宏在生成的结构体上生成#[derive(...)]属性。

注意：当此选项与skip_attributes选项一起使用时，derive属性仍将添加到生成的结构体中。

rename

用法示例：#[partially(rename = "MyGeneratedStruct")]

指示宏使用给定的标识符作为生成的结构体名称。默认情况下，使用PartialBaseStructName，其中BaseStructName是原始结构体的名称。

attribute

用法示例：#[partially(attribute(serde(rename_all = "PascalCase")))]

指示宏向生成的结构体添加额外的属性。默认情况下，基础结构体上定义的属性会转发到生成的结构体，除非存在skip_attributes选项。

skip_attributes

用法示例：#[partially(skip_attributes)]

指示宏跳过将属性从原始结构体转发到生成的结构体。默认情况下，基础结构体上的所有属性都会添加到生成的结构体中。

注意：当此选项与derive选项一起使用时，derive属性仍将添加到生成的结构体中。

注意：当此选项与`attribute》选项一起使用时，指定的属性仍将添加到生成的结构体中。

crate

用法示例：#[partially(crate = "my_partially_crate")]

指示宏对Partial特性实现使用不同的基础路径。默认情况下使用partially。如果你fork了partially crate，这会很有用。

字段选项

rename

用法示例：#[partially(rename = "new_field_name")]

指示宏为生成的字段使用给定的标识符。默认情况下使用与基础结构体相同的名称。

omit

用法示例：#[partially(omit)]

指示宏从生成的结构体中省略该字段。默认情况下不省略任何字段。

transparent

用法示例：#[partially(transparent)]

指示宏跳过将生成的字段包装在Option<T>中，而是透明地将字段类型镜像到生成的结构体中。

as_type

用法示例：#[partially(as_type = "Option<f32>")]

指示宏在生成字段时使用提供的类型而不是Option<T>。请注意，提供的类型将按原样使用，因此如果你期望Option<T>值，则需要手动指定。

注意：使用as_type时，给定类型必须Into<BaseType>，其中BaseType是原始字段类型。这对于Partial特性实现是必需的。

完整示例代码

use partially::Partial;

// 定义一个更复杂的基础结构体
#[derive(Partial, Debug)]
#[partially(derive(Debug, Default, Clone))]
#[partially(rename = "MyPartialData")]
#[partially(attribute(serde(rename_all = "camelCase")))]
struct UserData {
    id: u64,
    #[partially(rename = "user_name")]
    name: String,
    #[partially(omit)]
    password: String,
    #[partially(transparent)]
    is_active: bool,
    #[partially(as_type = "Option<f32>")]
    score: f64,
}

fn main() {
    // 使用默认值创建部分结构体
    let mut partial = MyPartialData::default();
    println!("Default partial: {:?}", partial);

    // 设置部分值
    partial.user_name = Some("Alice".to_string());
    partial.is_active = true; // 透明字段，不需要Option
    partial.score = Some(85.5); // 使用as_type指定的类型

    // 创建基础结构体
    let mut user = UserData {
        id: 1,
        name: "Bob".to_string(),
        password: "secret".to_string(),
        is_active: false,
        score: 70.0,
    };

    println!("Before apply: {:?}", user);

    // 应用部分更新
    let changes_applied = user.apply_some(partial.clone());
    println!("Changes applied: {}", changes_applied);
    println!("After apply: {:?}", user);

    // 检查透明字段
    assert!(user.is_active);
    // 检查重命名字段
    assert_eq!(user.name, "Alice");
    // 检查as_type字段
    assert_eq!(user.score, 85.5);
    // 检查被忽略的字段
    assert_eq!(user.password, "secret");
}

这个完整示例展示了：

1. 使用rename选项自定义生成的结构体名称
2. 使用attribute选项添加serde属性
3. 使用omit选项跳过某些字段
4. 使用transparent选项使字段不包装在Option中
5. 使用as_type选项自定义字段类型
6. 展示了如何应用部分更新并验证结果