过程宏概述
核心概念
过程宏(procedural macro)是 Rust 中另一类宏,与声明宏(macro_rules!)不同,它本质上是一个在编译时运行的 Rust 函数——接收一段代码的 TokenStream 作为输入,返回一段新的 TokenStream 作为输出。过程宏可以对代码进行任意复杂的分析和转换,比声明宏灵活得多。
过程宏必须定义在一个独立的 crate 中,这个 crate 的 Cargo.toml 中需要设置 proc-macro = true。过程宏在编译时作为编译器插件被加载执行,它可以访问完整的 Rust 语法树,能够生成任意复杂的代码。
Rust 提供三种过程宏:
- 派生宏(Derive macro):通过
#[derive(MyMacro)]使用,为结构体/枚举自动生成 trait 实现 - 属性宏(Attribute macro):通过
#[my_attr]使用,可以修改或替换被标注的项 - 函数宏(Function-like macro):通过
my_macro!(...)使用,语法与声明宏类似但功能更强
// 过程宏 crate 的 Cargo.toml 配置
// [lib]
// proc-macro = true
// 过程宏的基本签名
// use proc_macro::TokenStream;
//
// // 派生宏
// #[proc_macro_derive(MyDerive)]
// pub fn my_derive(input: TokenStream) -> TokenStream { ... }
//
// // 属性宏
// #[proc_macro_attribute]
// pub fn my_attr(attr: TokenStream, item: TokenStream) -> TokenStream { ... }
//
// // 函数宏
// #[proc_macro]
// pub fn my_fn_macro(input: TokenStream) -> TokenStream { ... }
fn main() {
// 以下是使用过程宏的示例(假设已定义)
// 派生宏:自动实现 trait
// #[derive(MyDerive)]
// struct Foo { x: i32 }
// 属性宏:修改函数行为
// #[my_attr]
// fn bar() { ... }
// 函数宏:自定义语法
// let result = my_fn_macro!(some custom syntax);
println!("过程宏在编译时执行,运行时没有开销");
}三种过程宏对比
| 特性 | 派生宏 | 属性宏 | 函数宏 |
|---|---|---|---|
| 使用语法 | #[derive(Name)] | #[name] | name!(...) |
| 输入 | 被标注的类型定义 | 属性参数 + 被标注的项 | 括号内的 token |
| 输出 | 追加到模块的新项 | 替换原始项 | 替换宏调用 |
| 能修改原始代码 | 不能 | 能 | 能 |
| 标注属性 | #[proc_macro_derive] | #[proc_macro_attribute] | #[proc_macro] |
| 常见用途 | 自动实现 trait | 条件编译、路由、日志 | 自定义 DSL |
过程宏的工作流程
// 过程宏的处理流程:
//
// 1. 编译器遇到过程宏调用
// 2. 将相关代码转换为 TokenStream
// 3. 调用过程宏函数,传入 TokenStream
// 4. 过程宏函数返回新的 TokenStream
// 5. 编译器用返回的 TokenStream 替换/追加代码
// 6. 继续正常编译
// TokenStream 是 token 的序列,每个 token 包含:
// - 类型(标识符、字面量、标点、分组)
// - 值
// - 位置信息(Span)
// 常用的辅助 crate:
// - syn:解析 TokenStream 为 Rust 语法树
// - quote:将 Rust 代码模板转换为 TokenStream
// - proc-macro2:proc_macro 的包装,支持在非过程宏上下文中使用
fn main() {
println!("过程宏流程:源码 → TokenStream → 宏函数 → TokenStream → 编译");
}过程宏 crate 的结构
// 过程宏 crate 的典型目录结构:
//
// my_macros/
// ├── Cargo.toml
// └── src/
// └── lib.rs
//
// 使用过程宏的 crate:
// my_app/
// ├── Cargo.toml
// └── src/
// └── main.rs
// === my_macros/Cargo.toml ===
// [package]
// name = "my_macros"
// version = "0.1.0"
// edition = "2021"
//
// [lib]
// proc-macro = true # 关键:声明这是过程宏 crate
//
// [dependencies]
// syn = { version = "2", features = ["full"] } # 解析
// quote = "1" # 生成代码
// proc-macro2 = "1" # TokenStream 包装
// === my_macros/src/lib.rs ===
// use proc_macro::TokenStream;
// use quote::quote;
// use syn::{parse_macro_input, DeriveInput};
//
// #[proc_macro_derive(HelloMacro)]
// pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
// let input = parse_macro_input!(input as DeriveInput);
// let name = input.ident;
//
// let expanded = quote! {
// impl HelloMacro for #name {
// fn hello() {
// println!("Hello from {}!", stringify!(#name));
// }
// }
// };
//
// TokenStream::from(expanded)
// }
// === my_app/Cargo.toml ===
// [dependencies]
// my_macros = { path = "../my_macros" }
// === my_app/src/main.rs ===
// use my_macros::HelloMacro;
//
// trait HelloMacro {
// fn hello();
// }
//
// #[derive(HelloMacro)]
// struct Pancakes;
//
// fn main() {
// Pancakes::hello(); // "Hello from Pancakes!"
// }
fn main() {
println!("过程宏必须在独立的 crate 中定义");
println!("常用依赖:syn(解析)、quote(生成)、proc-macro2(兼容)");
}声明宏 vs 过程宏
// 什么时候用声明宏,什么时候用过程宏?
// 声明宏(macro_rules!)适合:
// - 简单的代码模板替换
// - 重复模式生成
// - 不需要复杂逻辑的场景
// - 不想增加编译依赖
// 过程宏适合:
// - 需要解析复杂语法结构
// - 需要条件逻辑、循环等编程能力
// - 自动实现 trait(derive)
// - 自定义属性标注
// - 需要生成大量样板代码
fn main() {
println!("简单场景用 macro_rules!,复杂场景用过程宏");
}| 方面 | 声明宏 (macro_rules!) | 过程宏 |
|---|---|---|
| 定义方式 | 模式匹配 | Rust 函数 |
| 定义位置 | 任何 crate | 独立的 proc-macro crate |
| 复杂逻辑 | 有限(递归/模式) | 完整的 Rust 编程能力 |
| 依赖 | 无 | syn、quote 等 |
| 编译速度影响 | 小 | 较大(额外 crate 编译) |
| 卫生性 | 混合站点 | 调用站点(默认) |
| 调试难度 | 中等 | 较高 |
| 代码生成能力 | 受限于模式 | 无限 |
基本示例
// 展示过程宏的实际使用效果(不含宏定义,只展示使用端)
// 假设已有一个 derive 宏实现了 Builder 模式
// #[derive(Builder)]
// struct Server {
// host: String,
// port: u16,
// max_connections: u32,
// }
//
// 宏会自动生成:
// struct ServerBuilder {
// host: Option<String>,
// port: Option<u16>,
// max_connections: Option<u32>,
// }
// impl ServerBuilder {
// fn host(mut self, val: String) -> Self { self.host = Some(val); self }
// fn port(mut self, val: u16) -> Self { self.port = Some(val); self }
// fn max_connections(mut self, val: u32) -> Self { self.max_connections = Some(val); self }
// fn build(self) -> Result<Server, String> { ... }
// }
// 常见的过程宏库
// - serde: #[derive(Serialize, Deserialize)] 序列化
// - thiserror: #[derive(Error)] 错误类型
// - clap: #[derive(Parser)] 命令行解析
// - tokio: #[tokio::main] 异步运行时
// - sqlx: #[derive(FromRow)] 数据库映射
// - rocket: #[get("/")] 路由定义
fn main() {
// serde 示例概念
// #[derive(Serialize, Deserialize)]
// struct User { name: String, age: u32 }
// let json = serde_json::to_string(&user)?;
// thiserror 示例概念
// #[derive(Error, Debug)]
// enum AppError {
// #[error("IO 错误: {0}")]
// Io(#[from] std::io::Error),
// #[error("解析错误: {msg}")]
// Parse { msg: String },
// }
println!("过程宏让库能提供优雅的 API(如 serde、tokio)");
println!("大部分开发者是过程宏的使用者而非编写者");
}常见问题
问题一:过程宏为什么必须放在独立的 crate 中?
因为过程宏在编译时作为插件被加载执行。编译器需要先编译过程宏 crate 生成可执行代码,然后在编译使用者 crate 时加载运行。同一个 crate 不能既定义过程宏又使用过程宏。
问题二:过程宏会影响运行时性能吗?
不会。过程宏在编译时执行完毕,生成的代码与手写代码没有区别。但过程宏会增加编译时间(需要编译额外的 crate 和依赖)。
问题三:不写过程宏的开发者需要了解它吗?
需要了解基本概念。很多流行的 Rust 库都通过过程宏提供 API(serde 的 #[derive(Serialize)]、tokio 的 #[tokio::main] 等)。理解它们的工作原理有助于排查编译错误。
问题四:声明宏能完全被过程宏替代吗?
技术上可以,但不应该。声明宏更简单、编译更快、不需要额外依赖。只有当声明宏无法表达所需逻辑时才应使用过程宏。
适用场景
- 自动 trait 实现:序列化、错误类型、Builder 模式
- 框架注解:Web 路由、测试框架、ORM 映射
- 代码检查和转换:编译时验证、ABI 生成
- 自定义 DSL:SQL 查询、正则表达式编译时检查
注意事项
- 过程宏必须在独立的
proc-macrocrate 中定义 - 通常依赖
syn(解析)和quote(代码生成) - 过程宏错误信息需要手动提供(用
compile_error!或syn::Error) - 过程宏会增加编译时间
- 过程宏默认不是卫生的(调用站点卫生性)
- 过程宏不能访问运行时信息(文件内容、环境变量等的值在编译时确定)
总结
过程宏是在编译时运行的 Rust 函数,接收 TokenStream 并返回 TokenStream。分为三种:派生宏(#[derive])自动实现 trait,属性宏(#[attr])修改被标注的项,函数宏(name!())接受自定义语法。过程宏必须定义在独立的 proc-macro crate 中,通常依赖 syn 和 quote。与声明宏相比,过程宏拥有完整的 Rust 编程能力,可以处理任意复杂的代码转换,但编译时间更长且调试更难。大多数开发者是过程宏的使用者(通过 serde、tokio 等库),只有需要构建框架或消除大量样板代码时才需要编写过程宏。