proc_macro_derive ​

核心概念 ​

#[proc_macro_derive] 是标注派生宏入口函数的属性。它告诉编译器"这个函数是一个派生宏的实现"。当用户在类型上写 #[derive(MacroName)] 时,编译器会找到对应的 #[proc_macro_derive(MacroName)] 函数并调用它。

这个属性接受一个必选参数(宏名称)和一个可选的 attributes(...) 参数(辅助属性名列表)。函数签名必须是 pub fn name(input: TokenStream) -> TokenStream,输入是被标注类型的完整 token 序列,输出是要追加到当前模块的新代码。

rust
// proc_macro_derive 的基本用法
// 
// use proc_macro::TokenStream;
// 
// // 最简形式:只有宏名称
// #[proc_macro_derive(MyTrait)]
// pub fn my_trait_derive(input: TokenStream) -> TokenStream {
//     // input 包含被标注类型的完整定义
//     // 返回要追加的代码
//     TokenStream::new()  // 空输出 = 不追加任何代码
// }
// 
// // 带辅助属性
// #[proc_macro_derive(MyTrait, attributes(my_attr, my_other_attr))]
// pub fn my_trait_derive(input: TokenStream) -> TokenStream {
//     // 现在字段上可以使用 #[my_attr] 和 #[my_other_attr]
//     TokenStream::new()
// }

fn main() {
    println!("proc_macro_derive 是派生宏的核心标注属性");
}

函数签名与输入输出 ​

rust
// === 输入 TokenStream 的内容 ===
// 
// 假设用户写了:
// #[derive(MyMacro)]
// #[some_attr]
// pub struct User {
//     pub name: String,
//     pub age: u32,
// }
// 
// 输入 TokenStream 包含完整的类型定义:
// - 外部属性(#[some_attr],但不包含 #[derive(...)])
// - 可见性修饰符(pub)
// - 类型关键字(struct/enum/union)
// - 类型名(User)
// - 泛型参数(如果有)
// - 字段定义
// - 辅助属性(#[my_helper])

// === 输出 TokenStream 的规则 ===
// - 输出的代码会被追加到当前模块
// - 不能修改原始类型定义
// - 通常输出 impl 块
// - 可以输出多个 impl 块、函数、常量等
// - 输出空 TokenStream 表示不追加任何代码
// - 返回包含 compile_error! 的 TokenStream 会导致编译错误

fn main() {
    // 用 syn 解析输入的典型流程
    // let input = parse_macro_input!(input as DeriveInput);
    // 
    // DeriveInput 的结构:
    // DeriveInput {
    //     attrs: Vec<Attribute>,     // 外部属性
    //     vis: Visibility,           // 可见性
    //     ident: Ident,              // 类型名
    //     generics: Generics,        // 泛型参数
    //     data: Data,                // 类型数据(Struct/Enum/Union)
    // }
    //
    // Data::Struct 包含 Fields(字段列表)
    // Data::Enum 包含 Vec<Variant>(变体列表)

    println!("syn::DeriveInput 是解析输入的核心类型");
}

完整的派生宏实现示例 ​

rust
// === my_macros/src/lib.rs ===
// 
// use proc_macro::TokenStream;
// use quote::quote;
// use syn::{parse_macro_input, DeriveInput, Data, Fields};
// 
// /// 为结构体自动生成 describe 方法
// #[proc_macro_derive(Describe)]
// pub fn describe_derive(input: TokenStream) -> TokenStream {
//     let input = parse_macro_input!(input as DeriveInput);
//     let name = &input.ident;
//     let name_str = name.to_string();
//     
//     // 提取字段信息
//     let fields_info = match &input.data {
//         Data::Struct(data) => {
//             match &data.fields {
//                 Fields::Named(fields) => {
//                     let field_strs: Vec<String> = fields.named.iter()
//                         .map(|f| {
//                             let name = f.ident.as_ref().unwrap().to_string();
//                             let ty = quote!(#(&f.ty)).to_string();
//                             format!("  {}: {}", name, ty)
//                         })
//                         .collect();
//                     field_strs.join("\n")
//                 }
//                 Fields::Unnamed(fields) => {
//                     format!("  {} 个元组字段", fields.unnamed.len())
//                 }
//                 Fields::Unit => "  单元结构体".to_string(),
//             }
//         }
//         Data::Enum(data) => {
//             let variants: Vec<String> = data.variants.iter()
//                 .map(|v| format!("  {}", v.ident))
//                 .collect();
//             variants.join("\n")
//         }
//         Data::Union(_) => "  联合体".to_string(),
//     };
//     
//     let fields_str = fields_info;
//     
//     let expanded = quote! {
//         impl #name {
//             pub fn describe() -> String {
//                 format!("结构体 {} 的字段:\n{}", #name_str, #fields_str)
//             }
//         }
//     };
//     
//     TokenStream::from(expanded)
// }

// === my_app/src/main.rs ===
// use my_macros::Describe;
// 
// #[derive(Describe)]
// struct Server {
//     host: String,
//     port: u16,
//     max_conn: u32,
// }
// 
// fn main() {
//     println!("{}", Server::describe());
//     // 输出:
//     // 结构体 Server 的字段:
//     //   host: String
//     //   port: u16
//     //   max_conn: u32
// }

fn main() {
    println!("完整的派生宏实现包括:解析输入 → 提取信息 → 生成代码");
}

处理泛型 ​

rust
// 派生宏需要正确处理泛型参数
// syn 的 Generics 类型提供了方便的 split_for_impl 方法

// === 宏定义 ===
// #[proc_macro_derive(MyDebug)]
// pub fn my_debug(input: TokenStream) -> TokenStream {
//     let input = parse_macro_input!(input as DeriveInput);
//     let name = &input.ident;
//     
//     // split_for_impl 返回三部分:
//     // impl_generics: impl<T: Debug>
//     // ty_generics:   <T>
//     // where_clause:  where T: Display
//     let (impl_generics, ty_generics, where_clause) = 
//         input.generics.split_for_impl();
//     
//     let expanded = quote! {
//         impl #impl_generics std::fmt::Display for #name #ty_generics 
//             #where_clause 
//         {
//             fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
//                 write!(f, "{}", stringify!(#name))
//             }
//         }
//     };
//     
//     TokenStream::from(expanded)
// }

// === 使用侧 ===
// #[derive(MyDebug)]
// struct Wrapper<T: std::fmt::Debug> {
//     inner: T,
// }
// 
// // 宏展开后生成:
// // impl<T: Debug> Display for Wrapper<T> {
// //     fn fmt(&self, f: &mut Formatter) -> fmt::Result {
// //         write!(f, "Wrapper")
// //     }
// // }

fn main() {
    println!("split_for_impl() 是处理泛型的关键方法");
}

错误处理 ​

rust
// 派生宏中的错误应该返回编译时错误,而不是 panic

// === 好的错误处理 ===
// #[proc_macro_derive(StructOnly)]
// pub fn struct_only(input: TokenStream) -> TokenStream {
//     let input = parse_macro_input!(input as DeriveInput);
//     
//     match input.data {
//         Data::Struct(_) => {
//             // 正常处理...
//             let name = &input.ident;
//             let expanded = quote! {
//                 impl #name {
//                     pub fn is_struct() -> bool { true }
//                 }
//             };
//             TokenStream::from(expanded)
//         }
//         _ => {
//             // 返回编译错误,带有精确的位置信息
//             syn::Error::new_spanned(
//                 input.ident,
//                 "StructOnly 只能用于结构体,不支持枚举和联合体"
//             )
//             .to_compile_error()
//             .into()
//         }
//     }
// }

// === 收集多个错误 ===
// fn validate_fields(fields: &Fields) -> Result<(), syn::Error> {
//     let mut errors = Vec::new();
//     
//     if let Fields::Named(named) = fields {
//         for field in &named.named {
//             // 检查每个字段...
//             if some_condition {
//                 errors.push(syn::Error::new_spanned(
//                     field, "字段不合法"
//                 ));
//             }
//         }
//     }
//     
//     if errors.is_empty() {
//         Ok(())
//     } else {
//         // 合并所有错误
//         let mut combined = errors.remove(0);
//         for err in errors {
//             combined.combine(err);
//         }
//         Err(combined)
//     }
// }

fn main() {
    println!("用 syn::Error::new_spanned 提供精确的编译错误位置");
}

基本示例 ​

rust
// 展示 proc_macro_derive 的实际使用效果

// 标准库的 derive 宏都是通过类似机制实现的
#[derive(Debug, Clone, PartialEq, Default)]
struct DatabaseConfig {
    host: String,
    port: u16,
    database: String,
    max_connections: u32,
    timeout_secs: u64,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum Environment {
    Development,
    Staging,
    Production,
}

impl Default for Environment {
    fn default() -> Self {
        Environment::Development
    }
}

#[derive(Debug, Default)]
struct AppConfig {
    db: DatabaseConfig,
    env: Environment,
    debug: bool,
}

fn main() {
    // Default 派生宏生成的默认值
    let config = AppConfig::default();
    println!("默认配置: {:#?}", config);

    // Clone 派生宏生成的克隆方法
    let config2 = AppConfig {
        db: DatabaseConfig {
            host: "localhost".to_string(),
            port: 5432,
            database: "mydb".to_string(),
            max_connections: 10,
            timeout_secs: 30,
        },
        env: Environment::Production,
        debug: false,
    };
    println!("\n自定义配置: {:#?}", config2);

    // PartialEq 派生宏生成的比较
    let db1 = config.db.clone();
    let db2 = config.db.clone();
    println!("\n相等: {}", db1 == db2);

    // Hash 派生宏让枚举可以作为 HashMap 的 key
    let mut env_names = std::collections::HashMap::new();
    env_names.insert(Environment::Development, "开发");
    env_names.insert(Environment::Production, "生产");
    println!("环境: {}", env_names[&Environment::Production]);
}

常见问题 ​

问题一:proc_macro_derive 函数名必须和宏名相同吗?

不必。#[proc_macro_derive(MacroName)] 中的 MacroName 是用户使用 #[derive(MacroName)] 时写的名称,函数名可以是任意合法标识符。但按惯例,函数名通常是宏名的蛇形命名加 _derive 后缀。

问题二:一个 proc-macro crate 可以定义多个派生宏吗?

可以。一个 crate 可以定义任意数量的过程宏(派生、属性、函数宏混合都行),每个宏用一个独立的函数定义。

问题三:辅助属性会被编译器检查吗?

辅助属性本身是惰性的(inert),编译器不会对它们做任何检查。宏函数需要自己解析和验证辅助属性的内容。未声明的属性名会导致"unknown attribute"错误。

问题四:派生宏的输出可以引用私有项吗?

输出的代码在使用者的模块中展开,所以它遵循使用者的可见性规则。如果宏库需要在输出中引用自己的类型或函数,这些项必须是 pub 的。

适用场景 ​

  • trait 自动实现:为类型自动生成 trait 的 impl
  • 序列化/反序列化:serde 的 Serialize/Deserialize
  • Builder 模式:自动生成建造者 API
  • 验证框架:编译时数据验证
  • 代码元信息:提取类型的字段名、类型信息

注意事项 ​

  • 函数签名必须是 (TokenStream) -> TokenStream
  • 输入包含完整的类型定义(不含 #[derive] 本身)
  • 输出只能追加代码,不能修改原始类型
  • 辅助属性需要在属性中显式声明
  • 使用 syn::Error 而非 panic! 来报告错误
  • 泛型处理用 generics.split_for_impl()

总结 ​

#[proc_macro_derive(Name)] 是定义派生宏的核心属性,标注一个 (TokenStream) -> TokenStream 函数作为宏的入口。输入 TokenStream 包含被标注类型的完整定义,通过 syn 的 DeriveInput 解析可以提取类型名、泛型、字段等信息。输出 TokenStream 包含要追加到模块的新代码。通过 attributes(...) 可以声明辅助属性,让用户在字段级别提供额外配置。泛型处理用 split_for_impl() 方法。错误报告用 syn::Error::new_spanned() 提供精确位置。一个 proc-macro crate 可以定义多个派生宏。