12.4 宏调试与 hygiene 规则
Rust 宏在编译期展开，不生成独立的运行时调用栈，因此其调试方式与普通函数不同。同时，宏的卫生性（hygiene）机制影响变量和标识符的作用域，是理解宏行为的关键。本节将介绍如何有效调试宏代码，并解释 hygiene 规则如何保障宏的安全性。
调试声明宏
对于 macro_rules! 宏，最直接的调试方法是查看其展开后的代码。Rust 提供了以下工具：
使用 cargo expand
安装 cargo-expand 工具：
cargo install cargo-expand
然后运行：
cargo expand
它会输出整个 crate 在宏展开、但未进行类型检查前的代码。例如：
macro_rules! make_fn {
($name:ident) => {
fn $name() { println!("Called {}", stringify!($name)); }
};
}
make_fn!(hello);
执行 cargo expand 后可见：
fn hello() {
println!("Called {}", "hello");
}
这有助于验证宏是否按预期生成代码。
使用 trace_macros!（不稳定）
在 nightly Rust 中，可使用 trace_macros!(true); 让编译器打印宏展开过程：
#![feature(trace_macros)]
trace_macros!(true);
macro_rules! foo { () => { println!("foo"); } }
foo!();
trace_macros!(false);
编译时将输出展开日志。但该功能仅限 nightly，且输出较冗长，日常推荐使用 cargo expand。
调试过程宏
过程宏本质上是编译期运行的 Rust 程序，可通过以下方式调试：
日志输出
在过程宏函数中使用 eprintln! 或 dbg!，信息会出现在编译输出中：
#[proc_macro_derive(MyDerive)]
pub fn my_derive(input: TokenStream) -> TokenStream {
eprintln!("Input: {:?}", input);
// ...
}
注意：这些输出在 cargo build 时可见，但可能被其他编译信息淹没。
单元测试
为过程宏编写单元测试，模拟输入并验证输出：
#[test]
fn test_my_derive() {
let input = quote! {
struct MyStruct;
};
let output = my_derive_impl(input.into()).to_string();
assert!(output.contains("impl MyStruct"));
}
这要求将核心逻辑提取到非 proc_macro 函数中（因 TokenStream 在普通 crate 中不可用，需用 proc-macro2）。
使用 syn 的错误报告
当解析失败时，返回带有准确 span 的错误信息：
let ast = match syn::parse::<DeriveInput>(input.clone()) {
Ok(v) => v,
Err(e) => return e.to_compile_error().into(),
};
这样用户能直接在源码中标出错误位置。
Hygiene 规则
Hygiene 是 Rust 宏防止意外变量捕获的核心机制。它确保宏内部引入的标识符不会与调用上下文中的同名标识符冲突。
声明宏的 hygiene
在 macro_rules! 中，通过 $x:ident 捕获的标识符保留其原始作用域。例如：
macro_rules! bad_example {
($val:expr) => {{
let x = 10;
$val + x
}};
}
fn main() {
let x = 5;
println!("{}", bad_example!(x)); // 输出 15，而非 10
}
这里 $val 是 x（值为 5），宏内部的 x = 10 不会影响 $val 的绑定。但若宏直接写死 x，则使用宏内部的 x。
然而，macro_rules! 的 hygiene 对局部变量有效，但对项（如函数、trait）无效。这意味着宏可以安全地生成新函数名，但不能可靠地引用调用者作用域中的私有项。
过程宏的 hygiene
过程宏默认不卫生：生成的代码完全按照字面量解释。例如，若宏生成 vec![]，它依赖当前作用域中是否存在 vec。为避免此问题，应使用绝对路径或导入标准库项：
// 推荐：使用完整路径
quote! { ::std::vec::Vec::new() }
// 或通过 ident 捕获用户提供的路径（高级用法）
从 Rust 2021 起，过程宏支持更精细的 hygiene 控制（通过 Span::call_site() 或 Span::mixed_site()），但通常保持简单：生成的代码应自包含或明确依赖公开 API。
常见陷阱
- 变量遮蔽误解：误以为宏内变量会覆盖外部变量（实际不会，因 hygiene）；
- 路径依赖：过程宏生成的代码假设某些 trait 已导入（应使用完整路径）；
- 重复展开：宏递归调用无终止条件导致编译失败；
- token 类型错误：如将表达式传给期望类型的位置。
小结
调试宏的关键在于“看见”展开结果，cargo expand 是最实用的工具。而 hygiene 机制虽透明，却是宏安全性的基石——它让宏像黑盒一样工作，无需担心命名污染。理解这两点，能显著提升编写和维护宏的效率与可靠性。在实践中，应优先设计清晰、自包含的宏接口，并辅以充分测试。