hygiene 卫生性 ​

核心概念 ​

宏的卫生性(hygiene)是指宏展开后的代码不会意外地与调用者作用域中的变量名发生冲突。Rust 的声明宏具有"混合站点卫生性"(mixed-site hygiene):宏内部定义的局部变量、循环标签等不会泄露到外部作用域,也不会与外部同名变量冲突;但宏引用的类型、函数、模块等路径会在调用者的作用域中解析。

这意味着在 Rust 中,你不会遇到 C 语言宏那种经典的变量名冲突问题。宏内部的 let x = ... 创建的变量 x 和外部的 x 是不同的变量,互不影响。但如果宏需要引用标准库的类型或函数,需要用 $crate 或完整路径来确保在任何调用位置都能正确解析。

rust
// Rust 声明宏是卫生的:内部变量不会与外部冲突

macro_rules! make_x {
    ($val:expr) => {
        let x = $val;  // 这个 x 是宏内部的
        println!("宏内部 x = {}", x);
    };
}

fn main() {
    let x = 100;  // 外部的 x
    println!("外部 x = {}", x);

    make_x!(42);  // 宏内部创建了另一个 x

    // 外部的 x 没有被修改
    println!("外部 x 仍然 = {}", x);
}

卫生性的具体表现 ​

rust
// === 局部变量是卫生的 ===
macro_rules! hygiene_demo {
    () => {
        let result = 999;  // 宏内部的 result
        println!("宏内部: {}", result);
    };
}

// === 标签也是卫生的 ===
macro_rules! loop_macro {
    ($body:expr) => {
        // 宏内部的 'outer 标签不会与外部冲突
        'outer: loop {
            $body
            break 'outer;
        }
    };
}

fn main() {
    let result = 42;  // 外部的 result
    hygiene_demo!();   // 宏内部创建了另一个 result
    println!("外部 result: {}", result);  // 外部的不受影响

    // 即使外部也有 'outer 标签,也不冲突
    'outer: loop {
        loop_macro!(println!("内部循环"));
        break 'outer;
    }
}
rust
// === 宏参数中的变量在调用者作用域解析 ===
macro_rules! use_var {
    ($var:ident) => {
        // $var 在调用者的作用域中解析
        println!("变量值: {}", $var);
    };
}

fn main() {
    let my_value = 42;
    use_var!(my_value);  // 正确:my_value 在调用者作用域中存在

    // 宏内部定义的变量不能被外部访问
    macro_rules! define_secret {
        () => {
            let secret = 123;
            let _ = secret;
        };
    }

    define_secret!();
    // println!("{}", secret);  // 编译错误:secret 在外部不可见
}

$crate 路径 ​

rust
// 在库 crate 中定义宏时,需要用 $crate 引用本 crate 的项
// $crate 确保无论宏在哪里被调用,路径都能正确解析

// 假设这是一个库 crate 中的代码
pub fn helper() -> &'static str {
    "来自库的帮助函数"
}

#[macro_export]
macro_rules! safe_macro {
    () => {
        // 用 $crate 引用本 crate 的函数
        // 这样无论调用者如何重命名 crate,都能正确解析
        // 如果写成 crate::helper() 在外部 crate 中会出错
        println!("调用: {}", $crate::helper());
    };
}

// 不用 $crate 的问题
#[macro_export]
macro_rules! fragile_macro {
    () => {
        // 直接用路径——只在本 crate 内有效
        // 外部 crate 调用时会找不到 helper
        println!("helper");
    };
}

fn main() {
    safe_macro!();

    // 引用标准库类型时,用完整路径
    macro_rules! make_vec {
        ($($e:expr),*) => {
            {
                let mut v = ::std::vec::Vec::new();
                $(v.push($e);)*
                v
            }
        };
    }

    let v = make_vec!(1, 2, 3);
    println!("{:?}", v);
}

卫生性 vs 非卫生 ​

rust
// Rust 声明宏是部分卫生的
// 下面展示哪些是卫生的,哪些不是

// 卫生的(宏内部独立):
// - 局部变量 (let)
// - 循环标签 ('label)

// 不卫生的(在调用者作用域解析):
// - 类型名
// - 函数名
// - 模块路径
// - trait 名
// - 宏参数中传入的标识符

macro_rules! call_function {
    ($func:ident($($arg:expr),*)) => {
        // $func 在调用者的作用域解析
        $func($($arg),*)
    };
}

macro_rules! use_type {
    ($t:ty, $val:expr) => {
        // $t 在调用者的作用域解析
        let _v: $t = $val;
    };
}

fn double(x: i32) -> i32 { x * 2 }

fn main() {
    // 函数名在调用者作用域解析
    let result = call_function!(double(21));
    println!("double(21) = {}", result);

    // 类型名在调用者作用域解析
    use_type!(String, String::from("hello"));
    println!("类型解析正常");
}
元素卫生性说明
局部变量 (let)卫生不与外部变量冲突
循环标签 ('label)卫生不与外部标签冲突
类型名非卫生在调用者作用域解析
函数/方法名非卫生在调用者作用域解析
模块路径非卫生在调用者作用域解析
宏参数传入的 ident非卫生在调用者作用域解析
$crate特殊总是解析到定义宏的 crate

基本示例 ​

rust
// 展示卫生性在实际中的好处

// 安全的临时变量宏——不怕命名冲突
macro_rules! swap {
    ($a:expr, $b:expr) => {{
        // 在 C 的宏中,tmp 可能与外部变量冲突
        // 在 Rust 中完全安全
        let tmp = $a;
        $a = $b;
        $b = tmp;
    }};
}

// 安全的计数器宏
macro_rules! with_counter {
    ($body:block) => {{
        let mut count = 0;  // 这个 count 是宏内部的
        let result = $body;
        println!("块执行完毕,内部计数器: {}", count);
        let _ = count;
        result
    }};
}

// 利用 $crate 的跨 crate 安全宏
macro_rules! ensure {
    ($cond:expr, $msg:expr) => {
        if !($cond) {
            panic!("断言失败: {} (在 {}:{})", $msg, file!(), line!());
        }
    };
}

// 跨模块的宏使用
mod math {
    pub fn square(x: f64) -> f64 { x * x }

    macro_rules! apply_math {
        ($func:ident, $val:expr) => {
            // $func 在调用者的作用域解析
            $func($val)
        };
    }

    pub fn demo() {
        let result = apply_math!(square, 5.0);
        println!("square(5.0) = {}", result);
    }
}

fn main() {
    // swap 宏:内部的 tmp 不与外部冲突
    let tmp = "外部的 tmp";
    let mut a = 10;
    let mut b = 20;
    swap!(a, b);
    println!("swap: a={}, b={}", a, b);
    println!("外部 tmp 不受影响: {}", tmp);

    // with_counter:内部的 count 不与外部冲突
    let count = "外部的 count";
    with_counter!({
        println!("块内执行");
        42
    });
    println!("外部 count 不受影响: {}", count);

    // ensure
    ensure!(1 + 1 == 2, "数学坏了");
    println!("所有断言通过");

    // 模块中的宏
    math::demo();
}

常见问题 ​

问题一:为什么宏内部的变量名不能在外部使用?

因为卫生性。宏内部用 let 创建的变量属于宏的"卫生上下文",与调用者的上下文隔离。这是为了防止宏展开后意外覆盖外部变量或暴露内部实现细节。

问题二:如果我想让宏创建一个外部可用的变量怎么办?

通过参数传入标识符。用 $name:ident 捕获一个标识符,然后在宏内部用 let $name = ...。因为 $name 来自调用者的上下文,创建的变量在调用者的作用域中可见。

问题三:$crate 在 macro_rules! 中总是可用吗?

$crate 只在用 #[macro_export] 导出的宏中有意义。在同一个 crate 内部调用时,$crate 等同于 crate。在外部 crate 调用时,$crate 会自动解析到定义宏的 crate 名。

问题四:过程宏也有卫生性吗?

过程宏默认不是卫生的(call-site hygiene),生成的标识符在调用者的作用域中解析。这与声明宏的行为不同。过程宏需要手动使用 Span 来控制卫生性。

适用场景 ​

  • 安全的临时变量:宏内部可以自由使用临时变量名
  • 库宏导出:用 $crate 确保路径在任何位置都正确
  • 避免命名冲突:多次调用同一个宏不会变量冲突
  • 模块化宏设计:内部实现细节不泄露

注意事项 ​

  • 声明宏的局部变量和标签是卫生的
  • 类型、函数、模块路径不是卫生的(在调用者作用域解析)
  • 库 crate 中的宏应使用 $crate 引用本 crate 的项
  • 标准库类型应使用绝对路径如 ::std::vec::Vec
  • 过程宏的卫生性行为与声明宏不同
  • 宏参数中的标识符在调用者作用域解析

总结 ​

Rust 声明宏具有混合站点卫生性:宏内部的局部变量和循环标签是卫生的(不与外部冲突),但类型名、函数名等路径在调用者作用域解析(非卫生)。这让 Rust 宏比 C 宏安全得多,不用担心临时变量名冲突。宏参数中传入的标识符($name:ident)在调用者的作用域中解析,可以用来让宏创建外部可见的变量。库 crate 中导出的宏应使用 $crate 前缀来引用本 crate 的项,确保在任何调用位置都能正确解析路径。