Rust声明式宏

声明式宏（Declarative Macros）是提高代码复用性、减少样板代码（Boilerplate）的核心工具。它们通过 macro_rules! 关键字定义，本质上是一种基于模式匹配的语法替换系统。

以下是对声明式宏的深度解析：

1. 核心概念：模式匹配

声明式宏的工作方式类似于 match 表达式，但它匹配的是 Rust 源代码的 Token（语法标记），而不是运行时的值。

macro_rules! say_hello {
    // 匹配模式 => 展开后的代码
    () => {
        println!("Hello!");
    };
    ($name:expr) => {
        println!("Hello, {}!", $name);
    };
}

fn main() {
    say_hello!();             // 输出: Hello!
    say_hello!("Rust 2025");  // 输出: Hello, Rust 2025!
}

2. 片段分类符（Fragment Specifiers）

在宏定义中，$name:expr 里的 expr 就是分类符，告诉编译器匹配什么类型的语法：

• expr：表达式（如 2 + 2, "hello", my_func()）。
• ident：标识符（如函数名、变量名）。
• ty：类型（如 i32, Vec<String>）。
• path：路径（如 std::collections::HashMap）。
• stmt：语句（如 let x = 5）。
• block：代码块（用 {} 包围的内容）。
• tt：标记树（Token Tree），最强大的分类符，可以匹配几乎任何单体语法。

3. 重复匹配（Repetition）

这是宏处理列表数据的核心（如 vec![1, 2, 3] 的实现）。

语法格式：$( ... ) 分隔符 计数符

• *：重复 0 次或多次。
• +：重复 1 次或多次。
• ?：重复 0 次或 1 次。

关于分隔符使用的参考建议

• 匹配部（Matcher）：$(),* 里的逗号是必须的，用来告诉宏如何解析输入。
• 展开部（Transcriber）：
  • 如果生成的是语句（带 ; 的），不要写分隔符。
  • 如果生成的是列表元素（如 vec! 里的项），必须写逗号 , 作为分隔符。

示例：实现一个简化的求和宏

macro_rules! add_all {
    ($($x:expr),*) => {
        {
            let mut temp = 0;
            $(
                temp += $x;
            )* // 重复展开这行代码
            temp
        }
    };
}

let sum = add_all!(1, 2, 3, 4); // 展开为 temp += 1; temp += 2; ...

4. 声明式宏的独特优势

• 卫生性（Hygiene）：Rust 宏具有“卫生性”，这意味着宏内部定义的变量不会意外污染外部作用域，也不会被外部同名变量干扰。
• 变长参数：Rust 函数不支持变长参数，但宏可以（如 println!）。

• 编译期处理：宏在编译初期展开，不会产生运行时开销（零成本抽象）。

5. 与过程宏（Procedural Macros）的区别

 

特性	声明式宏 (macro_rules!)	过程宏 (#[derive], #[attr])
定义位置	可以在任何地方定义	必须在独立的 proc-macro crate 中
能力	基于模式匹配的代码替换	像编译器插件一样操作 Token 流
复杂度	简单、易读	复杂，需要处理 TokenStream
适用场景	简单的样板代码、简单的 DSL	自动实现 Trait、修改函数行为

6. 基础用法

安装expand：

cargo install cargo-expand

在 Rust 中，文件与模块通常是一一对应的。要查看某个 .rs 文件的展开结果，请使用该文件在项目中的模块路径：

• 查看某个模块（文件），在项目src目录下执行：

  cargo expand --offline module
  

  例如：若要查看 src/models/user.rs，通常对应命令为 cargo expand models::user。
• 查看特定项（函数或结构体）：

  cargo expand --offline module::MyStruct

• 查看 Bin (二进制目标)：

  cargo expand --offline --bin bin_name

7. 最佳实践提示

• 导出宏：如果你希望在其他 crate 中使用你的宏，需要添加 #[macro_export] 属性。
• 调试宏：如果宏报错难以理解，可以使用 cargo expand 命令（需安装）查看宏展开后的最终代码。
• 不要过度使用：宏会增加编译时间和代码阅读难度。如果能用普通函数或泛型解决，优先使用函数。

声明式宏是 Rust 提供的“超级语法糖”。通过掌握模式匹配和重复处理，你可以编写出极具表现力的 API，让代码从“命令式”转向“声明式”。 

参考：

Rust Reference: 声明式宏