自定义派生宏 Derive ​

核心概念 ​

派生宏(derive macro)是过程宏中最常用的一种,通过 #[derive(MacroName)] 语法为结构体、枚举或联合体自动生成代码。派生宏不能修改原始类型定义,只能在其基础上追加新的 impl 块或其他项。标准库中的 Debug、Clone、PartialEq 等都是内置的派生宏,第三方库如 serde 的 Serialize/Deserialize 则是自定义派生宏的典型代表。

派生宏的函数签名是 (TokenStream) -> TokenStream,输入是被标注类型的完整定义(包括属性、泛型等),输出是要追加到模块中的新项(通常是 impl 块)。派生宏通过 #[proc_macro_derive(Name)] 属性标注,还可以通过 attributes(...) 声明辅助属性。

rust
// === 过程宏 crate 侧(my_macros/src/lib.rs)===
// 
// use proc_macro::TokenStream;
// use quote::quote;
// use syn::{parse_macro_input, DeriveInput};
// 
// #[proc_macro_derive(Describe)]
// pub fn describe_derive(input: TokenStream) -> TokenStream {
//     // 将 TokenStream 解析为语法树
//     let input = parse_macro_input!(input as DeriveInput);
//     
//     // 获取类型名称
//     let name = &input.ident;
//     
//     // 生成代码
//     let expanded = quote! {
//         impl #name {
//             pub fn describe() -> &'static str {
//                 stringify!(#name)
//             }
//         }
//     };
//     
//     TokenStream::from(expanded)
// }

// === 使用侧(my_app/src/main.rs)===
// use my_macros::Describe;
// 
// #[derive(Describe)]
// struct User {
//     name: String,
//     age: u32,
// }
// 
// fn main() {
//     println!("类型: {}", User::describe());  // "User"
// }

fn main() {
    // 标准库的派生宏使用示例
    #[derive(Debug, Clone, PartialEq)]
    struct Point {
        x: f64,
        y: f64,
    }

    let p1 = Point { x: 1.0, y: 2.0 };
    let p2 = p1.clone();

    println!("{:?}", p1);           // Debug
    println!("相等: {}", p1 == p2); // PartialEq
}

派生宏的开发流程 ​

rust
// 开发派生宏的完整步骤:

// 第一步:创建过程宏 crate
// cargo new my_macros --lib

// 第二步:配置 Cargo.toml
// [lib]
// proc-macro = true
//
// [dependencies]
// syn = { version = "2", features = ["full"] }
// quote = "1"
// proc-macro2 = "1"

// 第三步:编写宏逻辑(my_macros/src/lib.rs)
//
// use proc_macro::TokenStream;
// use quote::quote;
// use syn::{parse_macro_input, DeriveInput, Data, Fields};
//
// #[proc_macro_derive(HelloMacro)]
// pub fn hello_macro(input: TokenStream) -> TokenStream {
//     let input = parse_macro_input!(input as DeriveInput);
//     let name = &input.ident;
//
//     // 检查是否是结构体
//     match &input.data {
//         Data::Struct(data) => {
//             // 获取字段信息
//             let field_names: Vec<_> = match &data.fields {
//                 Fields::Named(fields) => {
//                     fields.named.iter()
//                         .map(|f| f.ident.as_ref().unwrap())
//                         .collect()
//                 }
//                 _ => vec![],
//             };
//
//             let expanded = quote! {
//                 impl #name {
//                     pub fn field_names() -> Vec<&'static str> {
//                         vec![#(stringify!(#field_names)),*]
//                     }
//                 }
//             };
//             TokenStream::from(expanded)
//         }
//         _ => {
//             // 不支持枚举和联合体
//             let err = syn::Error::new_spanned(
//                 &input.ident,
//                 "HelloMacro 只支持结构体"
//             );
//             err.to_compile_error().into()
//         }
//     }
// }

// 第四步:在应用 crate 中使用
// [dependencies]
// my_macros = { path = "../my_macros" }
//
// use my_macros::HelloMacro;
//
// #[derive(HelloMacro)]
// struct Config {
//     host: String,
//     port: u16,
//     debug: bool,
// }
//
// fn main() {
//     println!("字段: {:?}", Config::field_names());
//     // ["host", "port", "debug"]
// }

fn main() {
    println!("派生宏开发流程:创建 crate → 配置 → 编写逻辑 → 使用");
}

辅助属性 ​

rust
// 派生宏可以定义辅助属性(helper attributes)
// 用于在字段或变体上提供额外的配置信息

// === 宏定义侧 ===
// #[proc_macro_derive(MySerialize, attributes(my_serde))]
// //                                ^^^^^^^^^^^^^^^^
// //                                声明辅助属性名
// pub fn my_serialize(input: TokenStream) -> TokenStream {
//     let input = parse_macro_input!(input as DeriveInput);
//     // 解析字段上的 #[my_serde(...)] 属性
//     // ...
// }

// === 使用侧 ===
// #[derive(MySerialize)]
// struct User {
//     #[my_serde(rename = "user_name")]   // 辅助属性
//     name: String,
//     
//     #[my_serde(skip)]                   // 辅助属性
//     password: String,
//     
//     age: u32,  // 无辅助属性
// }

// 实际例子:serde 的辅助属性
// #[derive(Serialize, Deserialize)]
// struct ApiResponse {
//     #[serde(rename = "statusCode")]
//     status_code: u32,
//     
//     #[serde(default)]
//     message: String,
//     
//     #[serde(skip_serializing_if = "Option::is_none")]
//     data: Option<String>,
// }

fn main() {
    println!("辅助属性让派生宏可以接收字段级别的配置");
    println!("serde 的 #[serde(rename)] 就是辅助属性的典型应用");
}

常见的派生宏库 ​

库派生宏用途
标准库Debug, Clone, Copy, PartialEq, Eq, Hash, Default基础 trait
serdeSerialize, Deserialize序列化/反序列化
thiserrorError错误类型定义
clapParser, Subcommand, Args命令行解析
sqlxFromRow数据库行映射
strumDisplay, EnumIter, EnumString枚举工具
derive_moreDisplay, From, Into, Add 等常用 trait 批量派生

基本示例 ​

rust
// 展示标准库派生宏的组合使用

#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
struct Config {
    host: String,
    port: u16,
    threads: usize,
}

impl Config {
    fn new(host: &str, port: u16) -> Self {
        Config {
            host: host.to_string(),
            port,
            threads: num_cpus(),
        }
    }
}

fn num_cpus() -> usize { 4 }

// 枚举也可以派生
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum LogLevel {
    Error,
    Warn,
    Info,
    Debug,
    Trace,
}

impl Default for LogLevel {
    fn default() -> Self {
        LogLevel::Info
    }
}

// 泛型结构体的派生
#[derive(Debug, Clone, PartialEq)]
struct Pair<T> {
    first: T,
    second: T,
}

impl<T: Default> Default for Pair<T> {
    fn default() -> Self {
        Pair {
            first: T::default(),
            second: T::default(),
        }
    }
}

fn main() {
    // Debug
    let config = Config::new("localhost", 8080);
    println!("{:?}", config);
    println!("{:#?}", config);  // 美化打印

    // Clone
    let config2 = config.clone();

    // PartialEq
    println!("相等: {}", config == config2);

    // Default
    let default_config = Config::default();
    println!("默认: {:?}", default_config);

    // Hash(可以用作 HashMap 的 key)
    let mut counts = std::collections::HashMap::new();
    counts.insert(LogLevel::Error, 5);
    counts.insert(LogLevel::Warn, 12);
    println!("错误次数: {}", counts[&LogLevel::Error]);

    // 泛型
    let pair = Pair { first: 1, second: 2 };
    let pair2 = pair.clone();
    println!("{:?}, 相等: {}", pair, pair == pair2);
}

常见问题 ​

问题一:派生宏能修改原始结构体吗?

不能。派生宏只能在原始类型定义的基础上追加新的项(如 impl 块、函数等),不能修改字段、删除字段或改变类型定义。如果需要修改原始项,应使用属性宏。

问题二:多个 derive 宏的顺序重要吗?

通常不重要,因为每个派生宏独立运行。但如果一个宏生成的代码依赖另一个宏的输出,就需要注意顺序。实际中很少遇到这种情况。

问题三:派生宏支持泛型吗?

支持。syn 库的 DeriveInput 包含完整的泛型信息(generics 字段),宏可以提取泛型参数、约束等,生成正确的泛型 impl 块。大多数标准库派生宏都正确处理了泛型。

问题四:派生宏编译报错时怎么调试?

用 cargo expand 查看宏展开后的完整代码。在宏内部用 syn::Error::new_spanned() 返回带位置信息的编译错误。也可以用 eprintln! 在编译时打印调试信息。

适用场景 ​

  • 自动实现标准 trait:Debug、Clone、PartialEq 等
  • 序列化框架:serde 的 Serialize/Deserialize
  • ORM 映射:数据库行到结构体的转换
  • 命令行工具:clap 的参数解析
  • Builder 模式:自动生成建造者结构体

注意事项 ​

  • 派生宏不能修改原始类型定义
  • 派生宏必须定义在独立的 proc-macro crate 中
  • 辅助属性需要在 #[proc_macro_derive] 中声明
  • 生成的代码应该处理泛型和生命周期
  • 错误信息应使用 syn::Error 提供精确的位置信息
  • 过度使用派生宏会增加编译时间

总结 ​

派生宏通过 #[derive(Name)] 为类型自动生成代码,是过程宏中最常用的一种。它接收类型定义的 TokenStream,返回要追加到模块中的新项(通常是 impl 块)。派生宏不能修改原始类型,只能追加。通过辅助属性(#[macro_helper(...)])可以在字段级别提供额外配置。开发派生宏需要在独立的 proc-macro crate 中,通常依赖 syn 解析语法树和 quote 生成代码。标准库、serde、thiserror、clap 等都大量使用派生宏来提供简洁的 API。