写过 Rust 代码的朋友，大多经历过这样的场景：
对着编辑器，机械地重复复制粘贴相同的函数，只是类型换了一下——print_i32、print_i64、print_u32……写到第 20 个时，手已经疲惫不堪，心里忍不住嘀咕：“这些函数除了类型名称不同，逻辑完全一样啊？编译器就不能帮我自动生成吗？”
有这种想法，说明你已经触摸到元编程的门槛了。在 Rust 中，这项能力叫做宏（Macro）——它能帮你自动生成重复代码、创建领域特定语言（DSL）、在编译时执行计算，甚至完成普通函数做不到的事情。
不过话说回来，宏也是 Rust 中最难啃的骨头之一，有人戏称它是“黑魔法”。今天，咱们就来一层层揭开这层面纱，掌握 Rust 宏编程的核心技巧。
核心概念：宏是什么？
宏 vs 函数
先理清最根本的区别：
函数好比一位厨师，你点菜，他给你做一道菜（返回一个值）。
宏呢，它是个菜谱生成器——不直接做菜，而是帮你写出做菜的步骤（生成代码）。宏在编译时展开，函数则在运行时调用，这是 Rust 宏与函数最本质的差异。
宏的两种类型
Rust 里宏分为两类：
- Declarative Macros（声明式宏）——用
macro_rules!定义，靠模式匹配来展开，更常用、更简单。今天咱们重点聊它，它也是 Rust 宏编程入门的首选。 - Procedural Macros（过程宏）——用过程函数定义，更强大、更灵活，用于
derive、属性、函数式宏，这篇先不展开，下篇详细讲解。
为什么宏的名字后面都要加个 !？
这是 Rust 的惯例，提醒你：这东西不是普通函数，它在编译时执行特殊操作。常见的有 println!、vec!、format!、panic!、todo! 等等，掌握这些标志性符号有助于快速识别 Rust 宏。
代码示例：从入门到实战
1. 第一个 macro_rules! 宏
来个最简单的：
macro_rules! say_hello {
() => {
println!("Hello, Macro!");
};
}
fn main() {
say_hello!(); // 输出：Hello, Macro!
}
展开之后，实际上就是直接调用了 println!。宏在编译时就把这段代码替换掉了，这种编译时代码替换机制是 Rust 宏高效的核心。
2. 带参数的宏
参数让宏真正有了灵活性：
macro_rules! print_value {
($value:expr) => {
println!("Value: {}", $value);
};
}
fn main() {
print_value!(42); // Value: 42
print_value!("Hello"); // Value: Hello
print_value!(vec![1, 2, 3]); // Value: [1, 2, 3]
}
语法上，$value 是参数名（以 $ 开头），:expr 是匹配器类型——这里表示匹配一个表达式。=> 后面就是展开规则。掌握这种匹配器语法是 Rust 宏编程的基础。
3. 多个匹配规则
宏可以像 match 一样有多个分支：
macro_rules! print_type {
($value:expr, i32) => {
println!("i32: {}", $value);
};
($value:expr, String) => {
println!("String: {}", $value);
};
($value:expr, $type:ty) => {
println!("{}: {}", stringify!($type), $value);
};
}
fn main() {
print_type!(42, i32); // i32: 42
print_type!("Hi", String); // String: Hi
print_type!(3.14, f64); // f64: 3.14
}
常用匹配器一览：
| 匹配器类型 | 匹配内容 | 示例 |
|---|---|---|
:expr | 表达式 | 1+2, func() |
:ident | 标识符 | x, my_var |
:literal | 字面量 | 42, "hello" |
:ty | 类型 | i32, Vec |
:pat | 模式 | Some(x), _ |
:stmt | 语句 | let x = 1; |
:tt | Token Tree | 任意 token |
4. 重复匹配——这才是宏真正开挂的地方
函数面对不定数量参数往往束手无策，但宏可以轻松应对：
macro_rules! vector {
($($elem:expr),*) => {{
let mut vec = Vec::new();
$(vec.push($elem);)*
vec
}};
}
fn main() {
let v1 = vector![]; // 空 Vec
let v2 = vector![1, 2, 3]; // [1, 2, 3]
let v3 = vector!["a", "b", "c"]; // ["a", "b", "c"]
}
这里的 ($($elem:expr),*) 匹配逗号分隔的表达式列表，然后 $(vec.push($elem);)* 将每个元素展开成一条 push 语句。* 表示零次或多次（还可以用 + 表示一次或多次，? 表示零次或一次）。这种重复模式是 Rust 宏实现变长参数和代码生成的关键。
5. 实战：简化版 vec!
macro_rules! my_vec {
() => {
Vec::new()
};
($($elem:expr),+) => {{
let mut temp_vec = Vec::new();
$(temp_vec.push($elem);)+
temp_vec
}};
}
fn main() {
let v1: Vec = my_vec![];
let v2 = my_vec![1, 2, 3, 4, 5];
let v3 = my_vec!["hello", "world"];
println!("v2: {:?}", v2); // [1, 2, 3, 4, 5]
}
6. 创建 DSL：SQL 查询宏
用宏可以很轻松地搭建一个简单的 SQL 查询构造器，让你体验 Rust 宏在领域特定语言中的应用潜力：
macro_rules! query {
(SELECT * FROM $table:ident) => {
format!("SELECT * FROM {}", stringify!($table))
};
(SELECT $($cols:ident),+ FROM $table:ident WHERE $where:ident = $value:expr) => {
format!(
"SELECT {} FROM {} WHERE {} = {:?}",
stringify!($($cols),+),
stringify!($table),
stringify!($where),
$value
)
};
}
fn main() {
let q1 = query!(SELECT * FROM users); // SELECT * FROM users
let q2 = query!(SELECT id, name FROM users WHERE age = 18);
// SELECT id, name FROM users WHERE age = 18
}
7. 自动实现 Debug——几乎可以媲美 derive 宏
macro_rules! impl_debug {
($($struct_name:ident { $($field:ident),* }),*) => {
$(
impl std::fmt::Debug for $struct_name {
fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
write!(f,
"{} {{ {} }}",
stringify!($struct_name),
$(format!("{}: {:?}", stringify!($field), self.$field)).join(", ")
)
}
}
)*
};
}
struct Point { x: i32, y: i32 }
struct Person { name: String, age: u32 }
impl_debug!(Point { x, y }, Person { name, age });
fn main() {
let p = Point { x: 1, y: 2 };
println!("{:?}", p); // Point { x: 1, y: 2 }
let person = Person { name: "Alice".to_string(), age: 30 };
println!("{:?}", person); // Person { name: "Alice", age: 30 }
}
常见坑点
坑点 1：宏的作用域
宏默认只在定义它的模块内可见，想要导出到 crate 根，需要加上 #[macro_export]：
mod my_module {
macro_rules! hello {
() => { println!("Hello!"); };
}
}
fn main() {
hello!(); // ❌ 错误：宏不在作用域
}
// ✅ 正确做法
#[macro_export]
macro_rules! hello {
() => { println!("Hello!"); };
}
坑点 2：宏展开顺序
宏在编译时展开，不是运行时。这意味着下面代码中的 add! 在编译时就已经替换成 x + 10：
macro_rules! add {
($a:expr, $b:expr) => { $a + $b };
}
fn main() {
let x = 5;
let result = add!(x, 10); // 编译时展开为 x + 10
println!("{}", result); // 15
}
坑点 3：重复捕获变量——变量名冲突
宏内部如果用了一个与外部同名的变量，可能会意外覆盖外部变量：
macro_rules! bad_macro {
($x:expr) => {{
let x = $x; // 可能覆盖外部的 x
x + 1
}};
}
fn main() {
let x = 10;
let result = bad_macro!(5); // 外部的 x 被覆盖了！
}
// ✅ 正确做法：使用唯一变量名
macro_rules! good_macro {
($x:expr) => {{
let __macro_x = $x;
__macro_x + 1
}};
}
坑点 4：调试困难
宏一旦出问题，错误信息往往让人一头雾水。推荐用 cargo expand 查看展开后的代码，这是 Rust 宏调试的最佳实践：
cargo install cargo-expand
cargo expand > expanded.rs
实战案例：一个日志宏
把上面学到的知识点串起来，写个可用的日志宏，展示 Rust 宏在实际项目中的代码生成能力：
macro_rules! log {
($msg:expr) => {{
let now = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap();
println!("[{}] {}", now.as_secs(), $msg);
}};
($level:expr, $msg:expr) => {{
let now = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap();
println!("[{}][{}] {}", now.as_secs(), $level, $msg);
}};
($level:expr, $msg:expr, $($args:expr),+) => {{
let now = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap();
println!("[{}][{}] {}", now.as_secs(), $level, format!($msg, $($args),+));
}};
}
fn main() {
log!("Application started");
log!("INFO", "Processing request");
log!("ERROR", "Failed to connect: {}", "timeout");
// 输出：
// [1709856000] Application started
// [1709856000][INFO] Processing request
// [1709856000][ERROR] Failed to connect: timeout
}
小结
- 宏在编译时展开，函数在运行时调用——这是最核心的区别，也是 Rust 宏编程的精髓。
macro_rules!是声明式宏，用模式匹配定义展开规则，适合处理重复代码生成和 DSL 构建。- 常用匹配器：
:expr（表达式）、:ident（标识符）、:ty（类型）、:tt（Token Tree），掌握它们是 Rust 宏入门的关键。 - 重复匹配是宏的超能力——
($($tt:tt),*)可以匹配任意数量的参数，实现变长宏调用。 - 宏可以创建 DSL，让代码简洁又有表现力，适合构建自定义语法。
- 调试宏用
cargo expand查看展开后的代码，这是排查宏问题的利器。 - 用
#[macro_export]导出到 crate 根，确保宏跨模块可用。
金句：“宏帮你写代码，而非帮你运行代码。”
下篇预告
学完 macro_rules!，你可能觉得这已经够强了。但 Rust 还有更厉害的一层——过程宏（Procedural Macros）：自定义 derive 宏、属性宏、函数式宏、宏卫生（hygiene）以及更高级的调试技巧。敬请期待第 38 篇：高级宏！
