宏基础：声明宏（macro_rules!）的语法与模式匹配

说到 Rust 的宏，很多人第一反应是「这玩意儿好难」。说实话，我刚开始接触时也这么觉得。但后来我发现，声明宏其实没那么神秘——它本质上就是一个编译期的模式匹配引擎。

你想想看，我们平时写函数，是在运行时处理数据。而宏呢？它是在编译时处理代码。说白了，宏就是帮你写代码的代码。

声明宏的基本语法

先看一个最简单的例子：

macro_rules! say_hello {
    () => {
        println!("Hello, world!");
    };
}

fn main() {
    say_hello!();
}

这个宏没有任何参数，调用时直接打印一句话。嗯，确实很简单。但实际项目中，我们很少写这么简单的宏。

模式匹配：宏的核心机制

声明宏的匹配规则，和 Rust 的 match 表达式非常像。每个分支由两部分组成：

• 左侧：匹配模式（matcher）
• 右侧：展开后的代码（transcriber）

我在项目中遇到过这样一个场景：需要根据不同的参数类型生成不同的结构体实现。用宏来做这件事，比手写几十遍代码要优雅得多。

macro_rules! create_getter {
    // 匹配 &self 的情况
    (&$self:ident, $field:ident, &$type:ty) => {
        fn $field(&$self) -> &$type {
            &self.$field
        }
    };
    // 匹配 &mut self 的情况
    (&mut $self:ident, $field:ident, &mut $type:ty) => {
        fn $field(&mut $self) -> &mut $type {
            &mut self.$field
        }
    };
}

这里用到了几个关键的模式匹配元素：

• $self:ident：匹配一个标识符（identifier）
• $field:ident：匹配字段名
• $type:ty：匹配类型

重复操作符：*、+、?

这是声明宏里最强大的部分。没有重复操作符，你只能处理固定数量的参数。有了它们，你可以处理任意数量的参数。

操作符	含义	示例
*	零次或多次	$( $x:expr ),*
+	一次或多次	$( $x:expr ),+
?	零次或一次	$( $x:expr )?

我曾经写过一个日志宏，需要支持可变数量的参数。用 + 操作符，几行代码就搞定了：

macro_rules! log_info {
    ($fmt:expr, $($arg:expr),+) => {
        println!("[INFO] {}", format!($fmt, $($arg),+));
    };
    ($fmt:expr) => {
        println!("[INFO] {}", $fmt);
    };
}

// 使用示例
log_info!("用户登录成功");
log_info!("用户 {} 在 {} 登录", "Alice", "2024-01-01");

这里有两个分支：

• 第一个分支用 + 匹配一个或多个参数
• 第二个分支匹配零个额外参数

重复模式中的分组与嵌套

有时候你需要更复杂的重复模式。比如生成一个键值对列表：

macro_rules! build_map {
    ( $($key:expr => $value:expr),* ) => {{
        let mut map = std::collections::HashMap::new();
        $(
            map.insert($key, $value);
        )*
        map
    }};
}

fn main() {
    let map = build_map!(
        "name" => "Rust",
        "year" => 2015,
        "version" => "1.75"
    );
    println!("{:?}", map);
}

注意看 $()* 的用法：它包裹了要重复生成的代码块。每次匹配到一组 $key => $value，就会生成一次 map.insert($key, $value);。

使用 ? 操作符处理可选参数

? 操作符在 Rust 2021 版本中才稳定下来。它特别适合处理「有最好，没有也行」的场景。

macro_rules! create_struct {
    ($name:ident, $($field:ident: $type:ty),* $(, $extra:ident: $extra_type:ty)?) => {
        struct $name {
            $($field: $type),*
            $(,$extra: $extra_type)?
        }
    };
}

// 使用
create_struct!(Point, x: i32, y: i32);
create_struct!(Person, name: String, age: u8, email: String);

嗯，这里要注意：? 操作符只能出现一次，而且通常放在重复模式的最后。

知识体系总览

下面这张图总结了声明宏的核心概念和它们之间的关系：

实际项目中的避坑指南

我曾经在代码审查中看到过这样的宏：

// 错误的写法
macro_rules! bad_macro {
    ($x:expr, $y:expr) => {
        $x + $y  // 没有分号，也没有返回值
    };
}

这个宏的问题在于：它展开后是一个表达式，但调用者可能期望它是一个语句。更安全的做法是：

macro_rules! good_macro {
    ($x:expr, $y:expr) => {
        $x + $y  // 明确返回一个值
    };
    ($x:expr, $y:expr;) => {  // 支持语句形式
        let _ = $x + $y;
    };
}

说实话，声明宏的学习曲线确实有点陡。但一旦掌握了模式匹配和重复操作符，你会发现它比手写重复代码要高效得多。我个人建议：先从简单的日志宏开始练手，慢慢再尝试复杂的 DSL 设计。

记住一点：宏是用来减少重复的，不是用来炫技的。如果一段逻辑用普通函数就能搞定，就别硬上宏。