自定义派生宏 Derive
核心概念
派生宏(derive macro)是过程宏中最常用的一种,通过 #[derive(MacroName)] 语法为结构体、枚举或联合体自动生成代码。派生宏不能修改原始类型定义,只能在其基础上追加新的 impl 块或其他项。标准库中的 Debug、Clone、PartialEq 等都是内置的派生宏,第三方库如 serde 的 Serialize/Deserialize 则是自定义派生宏的典型代表。
派生宏的函数签名是 (TokenStream) -> TokenStream,输入是被标注类型的完整定义(包括属性、泛型等),输出是要追加到模块中的新项(通常是 impl 块)。派生宏通过 #[proc_macro_derive(Name)] 属性标注,还可以通过 attributes(...) 声明辅助属性。
// === 过程宏 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
}派生宏的开发流程
// 开发派生宏的完整步骤:
// 第一步:创建过程宏 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 → 配置 → 编写逻辑 → 使用");
}辅助属性
// 派生宏可以定义辅助属性(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 |
| serde | Serialize, Deserialize | 序列化/反序列化 |
| thiserror | Error | 错误类型定义 |
| clap | Parser, Subcommand, Args | 命令行解析 |
| sqlx | FromRow | 数据库行映射 |
| strum | Display, EnumIter, EnumString | 枚举工具 |
| derive_more | Display, From, Into, Add 等 | 常用 trait 批量派生 |
基本示例
// 展示标准库派生宏的组合使用
#[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。