过程宏概述 ​

核心概念 ​

过程宏(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!(...) 使用,语法与声明宏类似但功能更强
rust
// 过程宏 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

过程宏的工作流程 ​

rust
// 过程宏的处理流程:
//
// 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 的结构 ​

rust
// 过程宏 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 过程宏 ​

rust
// 什么时候用声明宏,什么时候用过程宏?

// 声明宏(macro_rules!)适合:
// - 简单的代码模板替换
// - 重复模式生成
// - 不需要复杂逻辑的场景
// - 不想增加编译依赖

// 过程宏适合:
// - 需要解析复杂语法结构
// - 需要条件逻辑、循环等编程能力
// - 自动实现 trait(derive)
// - 自定义属性标注
// - 需要生成大量样板代码

fn main() {
    println!("简单场景用 macro_rules!,复杂场景用过程宏");
}
方面声明宏 (macro_rules!)过程宏
定义方式模式匹配Rust 函数
定义位置任何 crate独立的 proc-macro crate
复杂逻辑有限(递归/模式)完整的 Rust 编程能力
依赖无syn、quote 等
编译速度影响小较大(额外 crate 编译)
卫生性混合站点调用站点(默认)
调试难度中等较高
代码生成能力受限于模式无限

基本示例 ​

rust
// 展示过程宏的实际使用效果(不含宏定义,只展示使用端)

// 假设已有一个 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-macro crate 中定义
  • 通常依赖 syn(解析)和 quote(代码生成)
  • 过程宏错误信息需要手动提供(用 compile_error! 或 syn::Error)
  • 过程宏会增加编译时间
  • 过程宏默认不是卫生的(调用站点卫生性)
  • 过程宏不能访问运行时信息(文件内容、环境变量等的值在编译时确定)

总结 ​

过程宏是在编译时运行的 Rust 函数,接收 TokenStream 并返回 TokenStream。分为三种:派生宏(#[derive])自动实现 trait,属性宏(#[attr])修改被标注的项,函数宏(name!())接受自定义语法。过程宏必须定义在独立的 proc-macro crate 中,通常依赖 syn 和 quote。与声明宏相比,过程宏拥有完整的 Rust 编程能力,可以处理任意复杂的代码转换,但编译时间更长且调试更难。大多数开发者是过程宏的使用者(通过 serde、tokio 等库),只有需要构建框架或消除大量样板代码时才需要编写过程宏。