声明宏 macro_rules!
核心概念
声明宏(declarative macro)是 Rust 中最常用的宏类型,使用 macro_rules! 定义。它的工作原理类似于模式匹配:你定义一组模式(matcher),当宏调用时,Rust 编译器会将传入的代码片段与这些模式进行匹配,匹配成功后按照对应的模板(transcriber)展开为新的代码。整个过程在编译时完成,不产生任何运行时开销。
标准库中大量使用了声明宏,比如 println!、vec!、assert!、assert_eq! 等。宏名称后面的感叹号 ! 是调用宏的标志,用来与普通函数调用区分开。
声明宏与函数的本质区别在于:函数在运行时被调用并传入值,而宏在编译时被展开并传入代码片段(token)。宏可以接受不定数量的参数,可以生成任意代码结构(包括新的类型定义、函数、impl 块等),这些都是函数做不到的。
// 定义一个最简单的声明宏
macro_rules! say_hello {
// () 是匹配器:匹配空参数
// => 之后是展开的代码
() => {
println!("Hello, Rust macro!");
};
}
// 带参数的宏
macro_rules! greet {
// $name:expr 表示匹配一个表达式,绑定到 $name
($name:expr) => {
println!("你好, {}!", $name);
};
}
// 多规则的宏
macro_rules! log {
// 无参数:打印默认消息
() => {
println!("[LOG] 无消息");
};
// 一个参数:打印消息
($msg:expr) => {
println!("[LOG] {}", $msg);
};
// 两个参数:级别 + 消息
($level:expr, $msg:expr) => {
println!("[{}] {}", $level, $msg);
};
}
fn main() {
say_hello!(); // Hello, Rust macro!
greet!("世界"); // 你好, 世界!
log!(); // [LOG] 无消息
log!("启动完成"); // [LOG] 启动完成
log!("ERROR", "连接失败"); // [ERROR] 连接失败
}宏的定义结构
// macro_rules! 的完整结构
// macro_rules! 宏名 {
// (模式1) => { 展开代码1 };
// (模式2) => { 展开代码2 };
// ...
// }
// 三种定界符都可以用于定义和调用
macro_rules! using_parens {
() => { println!("小括号定义") };
}
macro_rules! using_brackets {
() => { println!("方括号定义") };
}
macro_rules! using_braces {
() => { println!("花括号定义") };
}
fn main() {
// 调用时也可以用任意定界符
using_parens!(); // 小括号调用
using_brackets![]; // 方括号调用
using_braces!{}; // 花括号调用
// 习惯用法:
// - vec![] 方括号(类似数组语法)
// - println!() 小括号(类似函数调用)
// - macro_rules! name {} 花括号(类似代码块)
}宏展开过程
// 宏在编译时展开为实际的 Rust 代码
// 可以用 cargo expand 查看展开结果
macro_rules! make_function {
// 接收一个标识符,生成一个函数
($name:ident) => {
fn $name() {
println!("调用了函数: {}", stringify!($name));
}
};
}
// 展开后相当于:
// fn foo() { println!("调用了函数: foo"); }
// fn bar() { println!("调用了函数: bar"); }
make_function!(foo);
make_function!(bar);
macro_rules! make_struct {
// 接收结构体名和字段名,生成结构体定义
($name:ident, $field:ident, $ty:ty) => {
#[derive(Debug)]
struct $name {
$field: $ty,
}
};
}
// 展开后相当于:
// #[derive(Debug)]
// struct Point { value: f64 }
make_struct!(Point, value, f64);
fn main() {
foo(); // 调用了函数: foo
bar(); // 调用了函数: bar
let p = Point { value: 3.14 };
println!("{:?}", p);
}宏的作用域
// 声明宏的作用域与普通 item 不同
// 基于文本顺序(textual scope),必须先定义后使用
fn main() {
// 在函数内定义的宏只在之后的代码中可用
macro_rules! inner_macro {
() => { println!("内部宏") };
}
inner_macro!(); // 可以
// 宏定义之前不能调用
// 编译错误:cannot find macro `late_macro`
// late_macro!();
macro_rules! late_macro {
() => { println!("后定义的宏") };
}
late_macro!(); // 可以
// 宏可以在代码块中使用,离开块后不可用
{
macro_rules! block_macro {
() => { println!("块内宏") };
}
block_macro!(); // 可以
}
// block_macro!(); // 编译错误:离开了块作用域
}
// 模块间导出宏需要 #[macro_export]
#[macro_export]
macro_rules! public_macro {
() => { println!("公开的宏") };
}
// #[macro_export] 的宏会被提升到 crate 根作用域
// 其他 crate 通过 use crate_name::public_macro; 引入基本示例
// 实用宏示例合集
// 1. 自定义 vec-like 的集合初始化宏
macro_rules! hash_set {
// 匹配逗号分隔的表达式列表
($($elem:expr),* $(,)?) => {{
let mut set = std::collections::HashSet::new();
$(
set.insert($elem);
)*
set
}};
}
// 2. HashMap 初始化宏
macro_rules! hash_map {
($($key:expr => $value:expr),* $(,)?) => {{
let mut map = std::collections::HashMap::new();
$(
map.insert($key, $value);
)*
map
}};
}
// 3. 简单的计时宏
macro_rules! measure {
($label:expr, $block:expr) => {{
let start = std::time::Instant::now();
let result = $block;
let elapsed = start.elapsed();
println!("{}: {:?}", $label, elapsed);
result
}};
}
// 4. 条件编译打印宏(只在 debug 模式下输出)
macro_rules! debug_log {
($($arg:tt)*) => {
#[cfg(debug_assertions)]
{
print!("[DEBUG] ");
println!($($arg)*);
}
};
}
// 5. 为多个类型批量实现 trait
trait Describe {
fn describe(&self) -> String;
}
macro_rules! impl_describe {
// 对每个类型生成 impl 块
($($t:ty),*) => {
$(
impl Describe for $t {
fn describe(&self) -> String {
format!("{} (类型: {})", self, stringify!($t))
}
}
)*
};
}
impl_describe!(i32, i64, f32, f64, String);
fn main() {
// HashSet
let fruits = hash_set!["苹果", "香蕉", "橙子"];
println!("水果: {:?}", fruits);
// HashMap
let scores = hash_map! {
"Alice" => 95,
"Bob" => 87,
"Carol" => 92,
};
println!("分数: {:?}", scores);
// 计时
let sum = measure!("求和", {
(0..1_000_000).sum::<i64>()
});
println!("结果: {}", sum);
// 调试日志
debug_log!("当前值: {}", 42);
// 批量 trait 实现
println!("{}", 42_i32.describe());
println!("{}", 3.14_f64.describe());
}常见问题
问题一:宏和函数怎么选?
能用函数解决就用函数,函数有类型检查、更好的错误提示、更容易调试。当你需要接受不定数量的参数、生成新的类型或函数定义、减少重复的 trait 实现等"代码生成"场景时,才用宏。
问题二:为什么宏调用后面要加感叹号?
感叹号 ! 是 Rust 的语法约定,用来区分宏调用和函数调用。因为宏在编译时展开,行为和函数很不同(比如可以接受各种语法片段),加 ! 让开发者一眼就能看出这是宏调用。
问题三:macro_rules! 宏可以导出给其他 crate 用吗?
可以。使用 #[macro_export] 属性标注宏定义,它就会被导出到 crate 的根命名空间。其他 crate 通过 use your_crate::macro_name; 引入。注意 #[macro_export] 会忽略模块层级,直接放到 crate 根。
问题四:怎么调试宏展开?
安装 cargo-expand 工具(cargo install cargo-expand),然后运行 cargo expand 查看所有宏展开后的代码。也可以用 cargo expand --lib 或指定模块。stringify! 宏可以把代码片段转为字符串,方便打印调试。
适用场景
- 减少重复代码:为多个类型批量实现 trait
- 领域特定语言:创建类似 SQL、HTML 等 DSL 语法
- 集合初始化:vec!、自定义的 hash_map! 等
- 条件代码生成:根据参数生成不同的代码分支
- 可变参数:接受不定数量的参数
注意事项
- 声明宏基于文本顺序作用域,必须先定义后使用
- 宏的错误信息通常不如函数清晰,要注意调试
- 模式匹配按顺序进行,第一个匹配的规则会被使用
#[macro_export]会将宏提升到 crate 根,忽略模块层级- 宏内部的变量是卫生的(hygienic),不会与外部变量冲突
- Rust 2021 Edition 中
:pat片段说明符会匹配|模式
总结
macro_rules! 是 Rust 的声明宏系统,通过模式匹配在编译时展开代码。它接收代码片段(token),按照定义的规则生成新的代码,整个过程零运行时开销。声明宏可以接受不定数量的参数、生成任意代码结构(函数、结构体、impl 块等),是减少重复代码的主要工具。标准库中的 vec!、println!、assert! 等都是声明宏。宏的作用域基于文本顺序,必须先定义后使用;通过 #[macro_export] 可以导出给其他 crate 使用。在能用函数解决的场景下优先用函数,只在需要代码生成时才用宏。