proc_macro_derive
核心概念
#[proc_macro_derive] 是标注派生宏入口函数的属性。它告诉编译器"这个函数是一个派生宏的实现"。当用户在类型上写 #[derive(MacroName)] 时,编译器会找到对应的 #[proc_macro_derive(MacroName)] 函数并调用它。
这个属性接受一个必选参数(宏名称)和一个可选的 attributes(...) 参数(辅助属性名列表)。函数签名必须是 pub fn name(input: TokenStream) -> TokenStream,输入是被标注类型的完整 token 序列,输出是要追加到当前模块的新代码。
// 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 是派生宏的核心标注属性");
}函数签名与输入输出
// === 输入 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 是解析输入的核心类型");
}完整的派生宏实现示例
// === 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!("完整的派生宏实现包括:解析输入 → 提取信息 → 生成代码");
}处理泛型
// 派生宏需要正确处理泛型参数
// 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() 是处理泛型的关键方法");
}错误处理
// 派生宏中的错误应该返回编译时错误,而不是 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 提供精确的编译错误位置");
}基本示例
// 展示 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 可以定义多个派生宏。