macro_rules!：手写第一个Rust声明宏

可视化演示

展示图的广度优先搜索过程，从根节点A出发逐层访问，使用队列记录待访问节点。

宏的初识：菜谱还是厨师

你从后厨一沓菜谱里抽出最基础的一张——「万能炒菜模板」，上面写着：热锅、倒油、下主料、翻炒、出锅。这张卡片最大的秘密是：它可以无限复印。每来一桌客人都复印一份，填上不同的主料，就是一道新菜。这就是“模板”的威力：写一份，用一万次。

Rust 里的宏（macro）就是这样的模板。macro_rules! 是 Rust 提供的一种“声明式宏”写法：你声明规则，编译器负责“复印”。当代码中出现 macro_name!(...) 的调用时，编译器在编译期把调用替换成宏定义的展开内容。函数是运行期执行的“厨师”，宏是编译期工作的“抄写员”——这是理解宏的第一把钥匙。

先看一个最简例子：

要点有三个：macro_rules! 后跟宏名，花括号里放一条或多条规则；每条规则用 (模式) => (展开) 的箭头连接；调用时宏名后带 !。宏接收的不是“值”，而是“代码片段”，因此能做出函数做不到的语法级操作，比如生成新的变量名、新的语句块。

第一张菜谱卡的定位已经清楚：函数解决“怎么算”，宏解决“怎么把算的代码写出来”。凡是重复的样板代码，都可以考虑收进一张魔法菜谱。

macro_rules! hello {    () => {        println!("hello");    };} fn main() {    hello!(); // 编译期展开为 println!("hello");}

规则匹配：按菜名取卡

顾客喊“来个回锅肉”，后厨不会把整本菜谱翻完，而是先看每张卡片顶部的菜名标签，找到写着“回锅肉”的那张。macro_rules! 的每一条规则分支就是这样的标签：宏定义里可以写多条规则，编译器按从上到下的顺序尝试，第一条左侧模式与调用输入匹配成功的规则负责展开。

每条规则写成 (模式) => (展开)。模式里可以写死字面量，比如 vec![] 中的方括号、逗号；也可以用 $变量:类型 留出捕获位。以 vec! 为例，vec![] 匹配空参数，vec![1, 2, 3] 匹配带内容的参数——它们由不同的规则臂接住。

关键规则是“第一个命中者胜出”，而且要完整匹配输入。如果所有规则的左侧都无法匹配，编译器报错 no rules expected the token……，相当于后厨礼貌地告诉你“这菜我们真不会做”。另外，越具体的模式要写在越前面，如果把“空参数”这种通用模式放在最前，后面的模式就永远没机会接到菜。

点菜逻辑总结：模式是“菜名标签”，规则分支是“不同的做菜方案”，从上到下第一个能接住的就是正确答案。

捕获片段：食材空格

菜谱卡上刻意留出的空格，让一张卡能应付无数种主料。宏里的 $变量:片段类型符 就是这样的空格。例如模式 ($x:expr)，意思是“这里可以放任意一个表达式，把它记到变量 x 里”，展开时用 $x 就能把捕获的内容放回输出位置。

片段类型符（fragment specifier）决定了空格接受哪一类“食材”：

• expr：任意表达式，最常用；

• ty：类型，如 i32、Vec\<f32\>；

• ident：标识符，如变量名、函数名；

• literal：字面量，如 42、"hello"；

• tt：单棵 token 树，最通用的“原始食材”；

• path：路径，如 std::collections::HashMap。

展开区的 $x 必须与匹配区捕获的变量同名同类型。片段类型符越具体，匹配越严格，展开也越安全；tt 最宽，几乎什么都能接，但需要你自己进一步拆解。看个综合例子：

备菜逻辑：空格类型选对，后厨才知道该往里面填什么；用 tt 相当于“不管是什么先收着，回头自己切”。

macro_rules! make_pair {    ($a:expr, $b:expr) => {        ($a, $b)    };}let pair = make_pair!(1 + 1, "two"); // 展开为 (1 + 1, "two")

重复语法：一锅炒十份

最让厨师省心的是“批量指令”：菜谱上写「对每份配料：切片、下锅、翻炒」，一张卡能同时处理十份配料。宏的重复语法就是这个「对每份……」。$($x:expr),* 的含义是：把模式 $x:expr 重复零次或多次，重复单元之间用逗号分隔。调用 vec![1, 2, 3] 时，x 依次捕获 1、2、3——这正是 vec! 支持任意长度参数列表的秘密。

重复操作符有三个：

• *：零次或多次；

• +：一次或多次；

• ?：零次或一次（只用于单个可选片段）。

分隔符写在右括号前，如 $(...),* 的逗号。展开区必须用 $(...)* 这样的重复语法重新包裹被重复的变量，且只能引用在匹配区被重复捕获的变量，否则编译器直接报错。

重复还可以组合与嵌套：一个宏里可以有多个重复片段，比如同时捕获键值对 $( $k:expr => $v:expr ),*；重复单元内部也允许再套一层重复，相当于“对每组配料里的每片肉都做同样处理”。嵌套时每一层的变量必须严格对应，切莫串层。

批量做菜的威力：一次定义，编译期自动展开成 N 份；N 由调用方输入决定，这正是“可变参数”宏的秘密。

递归宏：菜谱套菜谱

菜谱里最神奇的一页：某张卡片上写着「想做好高汤，先做一份基础高汤；而基础高汤的做法，请看本页」。递归宏就是这样的“本页”。展开过程中，如果生成的新代码里又出现了对宏自身的调用，编译器会继续展开，直到输出里不再出现宏调用为止。

递归宏的经典用途是生成嵌套结构。比如要生成 n 层嵌套的函数调用 wrap(wrap( ... base() ... ))：第一条规则处理“只剩下一个参数”的终结情况；第二条规则处理“至少还有参数”的递推情况——输出一层 wrap，再把剩余的输入交给宏自身继续展开。

递归宏必须有终结条件（base case），否则会无限展开。Rust 编译器默认设置了递归深度上限（recursion limit，通常是 128 层），触顶即报错。这不是 bug，而是保护机制：让“无限膨胀的代码”在编译期就暴露，而不是把灾难带到运行期。

递归宏是“元编程的自相似”：写的时候先写终结分支，再写递推分支——顺序和后厨出菜一样，先想好“什么时候直接装盘”。

卫生与导出：密封料理包

菜谱借给隔壁饭馆最怕什么？你写「酱油一勺」，指的是你家特调酱，隔壁用他家的酱油一倒，味道全变了。Rust 宏的卫生性（hygiene）专门解决这个“串味”问题：宏内部引入的变量、标签，不会和调用处的同名标识符互相干扰。

具体来说，宏体里 let tmp = ... 定义的 tmp，并不会覆盖调用处已有的 tmp；反过来，调用处的变量也不会悄悄渗进宏内部。宏体中的标识符按“定义处”的作用域解析，调用方传入的表达式按“调用处”作用域解析。这让宏像密封料理包：打开时不会溅到别人的锅里。

可见性上是另一套规矩。宏不是函数，不能简单地加 pub。要把宏导出到 crate 之外，需要加 #[macro_export] 属性，它会将宏放到 crate 根部；crate 内部想限制范围，可以用 pub(crate) use some_macro; 让它在 crate 内可见。宏必须在展开前能被找到，所以通常先定义或 import 再使用。

厨房规矩收个尾：密封料理包（卫生性）保证味道不串；借菜谱要贴「#[macro_export]」标签，否则隔壁厨房根本找不到你的卡片。

测试与实战：上桌先试菜

菜谱交给新帮厨，怎么知道他照做不会出错？最好的办法是让他试做、你看成品。宏的问题也类似：它能不能编译通过、报错信息是否友善，需要“试菜”。trybuild 就是 Rust 生态里专门做“编译期试菜”的工具。

trybuild 的典型用法：在 tests 目录里写 UI 测试，调用 trybuild::TestCases 并传入一个目录路径，它会在测试中真实调用 rustc 编译这些文件。预期编译失败的样例，把期望的错误信息放在对应的 .stderr 文件里，trybuild 逐字比对；预期成功的样例直接编译即可。宏的报错行为因此被“快照”锁定，改坏宏时测试立刻变红。

设计原则与常见坑：宏要短小聚焦，输入输出以“代码”为对象，报错信息要指明是哪条规则失败。常见错误包括：展开区忘给重复变量加 *、片段类型符用错、递归宏没有 base case、用 ident 拼接时不小心破坏了卫生性。实战上记住一句：能用函数就不用宏，只有在需要“语法级灵活性”时才请出魔法菜谱。

试菜文化收尾：好的宏像稳定出品的招牌菜，口味恒定；trybuild 把“口味”固化成回归测试，让每一道宏菜都经得起时间检验。

AI 应用场景

Python 演示

"""模拟 macro_rules! 声明宏：捕获、重复与递归展开的极简演示"""  class MiniMacro:    """一张魔法菜谱卡：模式 + 展开模板"""     def __init__(self, name, template):        self.name = name        self.template = template        self.expand_count = 0     def expand(self, args):        self.expand_count += 1        return [self.template.replace("$x", a) for a in args]  def match_rule(rules, user_input):    for rule in rules:        if rule["match"] in user_input:            return rule["handler"]    return None  def expand_depth(n):    if n == 0:        return "base()"    return "wrap(" + expand_depth(n - 1) + ")"  def main():    vec = MiniMacro("vec", "push($x);")    lines = vec.expand(["1", "2", "3"])    print("vec![1,2,3] 展开结果：")    for line in lines:        print("  " + line)    print("展开次数:", vec.expand_count)     rules = [        {"match": "add", "handler": "执行加法"},        {"match": "sub", "handler": "执行减法"},    ]    print("命中规则:", match_rule(rules, "add"))     print("递归展开:", expand_depth(3))  if __name__ == "__main__":    main()

1. class MiniMacro:定义一张「菜谱卡」：宏名字 + 展开模板
2. self.expand_count += 1记录宏被调用的次数，对应编译期展开次数
3. self.template.replace("$x", a)把 $x 占位符替换成实际传入 token，模拟捕获
4. [self.template.replace("$x", a) for a in args]列表推导逐个替换，模拟 $(...)* 重复展开
5. for rule in rules:逐条尝试规则分支，模拟“从上到下第一个命中”
6. if rule["match"] in user_input:输入包含当前规则的关键字，即命中该分支
7. if n == 0:递归宏的终结条件，直接返回基础代码
8. return "wrap(" + expand_depth(n - 1) + ")"递推步：包一层后继续展开

常见误区

面试题