声明宏 macro_rules! ​

核心概念 ​

声明宏(declarative macro)是 Rust 中最常用的宏类型,使用 macro_rules! 定义。它的工作原理类似于模式匹配:你定义一组模式(matcher),当宏调用时,Rust 编译器会将传入的代码片段与这些模式进行匹配,匹配成功后按照对应的模板(transcriber)展开为新的代码。整个过程在编译时完成,不产生任何运行时开销。

标准库中大量使用了声明宏,比如 println!、vec!、assert!、assert_eq! 等。宏名称后面的感叹号 ! 是调用宏的标志,用来与普通函数调用区分开。

声明宏与函数的本质区别在于:函数在运行时被调用并传入值,而宏在编译时被展开并传入代码片段(token)。宏可以接受不定数量的参数,可以生成任意代码结构(包括新的类型定义、函数、impl 块等),这些都是函数做不到的。

rust
// 定义一个最简单的声明宏
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] 连接失败
}

宏的定义结构 ​

rust
// 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
// 宏在编译时展开为实际的 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);
}

宏的作用域 ​

rust
// 声明宏的作用域与普通 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; 引入

基本示例 ​

rust
// 实用宏示例合集

// 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 使用。在能用函数解决的场景下优先用函数,只在需要代码生成时才用宏。