Rust 的属性宏是什么

在 Rust 中，属性宏（Attribute Macros）是一种强大的元编程工具，用于在编译期处理代码结构（如结构体、函数、模块等），可以实现代码生成、验证、修改等功能。

weixin_44594317

1009人浏览 · 2025-09-12 15:47:14

weixin_44594317 · 2025-09-12 15:47:14 发布

在 Rust 中，属性宏（Attribute Macros） 是一种强大的元编程工具，用于在编译期处理代码结构（如结构体、函数、模块等），可以实现代码生成、验证、修改等功能。它们以 #[attr(...)] 的形式附加到 Rust 语法元素上，影响编译器对这些元素的处理方式。

一、属性宏的分类

Rust 中的属性宏主要分为两类：

内置属性（Built-in Attributes）：Rust 编译器原生支持的属性，有固定的语法和功能。
自定义属性宏（Custom Attribute Macros）：由开发者通过 procedural macros（过程宏）定义的属性，用于实现特定业务逻辑。

二、内置属性宏关键字（常用）

Rust 提供了许多内置属性，用于控制编译行为、代码检查、测试等核心功能。以下是一些常用的内置属性：

1. 编译控制

#[cfg(...)]：条件编译，根据条件决定是否编译某段代码。
示例：

#[cfg(windows)]
fn run_on_windows() {
    // 仅在 Windows 平台编译
}

#[cfg(unix)]
fn run_on_unix() {
    // 仅在 Unix 平台编译
}

#[cfg_attr(condition, attr)]：条件性地应用另一个属性。
示例：

#[cfg_attr(debug_assertions, debug_print)]  // 仅在 debug 模式下应用 debug_print 属性
fn process() {}

2. 错误与警告控制

#[allow(...)]：允许特定的编译器警告（抑制警告）。
示例：

#[allow(dead_code)]  // 允许未使用的代码，不产生警告
fn unused_function() {}

#[warn(...)]：将特定情况视为警告（即使默认是允许的）。
示例：

#[warn(unused_variables)]  // 未使用的变量视为警告
fn main() {
    let x = 5;  // 会产生警告：unused variable `x`
}

#[deny(...)]：将特定情况视为错误（编译失败）。
示例：

#[deny(unused_variables)]  // 未使用的变量视为错误
fn main() {
    let x = 5;  // 编译失败：error: unused variable `x`
}

#[forbid(...)]：比 deny 更严格，无法被外层的 allow 覆盖。

3. 测试相关

#[test]：标记函数为测试函数，可通过 cargo test 运行。
示例：
```
#[test]
fn test_add() {
    assert_eq!(1 + 1, 2);
}
```

#[should_panic]：标记测试函数预期会 panic（如果不 panic 则测试失败）。
示例：

#[test]
#[should_panic(expected = "divide by zero")]
fn test_divide_by_zero() {
    1 / 0;
}

4. 代码文档

///：为紧随其后的元素生成文档（外部文档）。
//!：为当前模块生成文档（内部文档）。
#[doc(...)]：更精细地控制文档生成，例如隐藏元素或指定文档内容。
示例：
```
#[doc(hidden)]  // 不在生成的文档中显示该函数
fn internal_utility() {}
```

5. 类型与内存相关

#[repr(...)]：控制结构体/枚举在内存中的表示形式（用于 FFI 或底层操作）。
示例：

#[repr(C)]  // 按 C 语言的内存布局排列字段
struct MyStruct {
    a: u8,
    b: u32,
}

#[derive(...)]：自动生成 trait 实现（最常用的内置属性之一）。
示例：

#[derive(Debug, Clone)]  // 自动实现 Debug 和 Clone trait
struct Point { x: i32, y: i32 }

6. 模块与可见性

#[path(...)]：指定模块的实际文件路径（默认模块名与文件名一致）。
示例：

#[path = "my_module_impl.rs"]  // 加载 my_module_impl.rs 作为该模块的内容
mod my_module;

#[macro_use]：导入其他模块中的宏（Rust 2018 后逐渐被 use 替代）。

7. 其他常用内置属性

#[inline]：提示编译器内联该函数（优化建议）。
#[cold]：提示编译器该函数很少被调用（优化建议）。
#[no_mangle]：禁止编译器修改函数名（用于 FFI 中被其他语言调用）。

三、自定义属性宏

除了内置属性，开发者可以通过 过程宏（proc-macro） 定义自己的属性宏，实现灵活的代码生成逻辑。自定义属性宏需要在独立的 proc-macro 类型的 crate 中实现。

示例：简单的自定义属性宏

首先创建一个 proc-macro crate（Cargo.toml）：

[package]
name = "my_attr_macro"
version = "0.1.0"
edition = "2021"

[lib]
proc-macro = true

[dependencies]
proc-macro2 = "1.0"
quote = "1.0"
syn = { version = "2.0", features = ["full"] }

实现属性宏（src/lib.rs）：

use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

// 定义一个名为 `log_call` 的属性宏
#[proc_macro_attribute]
pub fn log_call(_attr: TokenStream, item: TokenStream) -> TokenStream {
    // 解析输入的函数代码
    let input = parse_macro_input!(item as DeriveInput);
    let ident = input.ident;  // 函数名

    // 生成新代码：调用函数前打印日志
    let expanded = quote! {
        fn #ident() {
            println!("Calling function: {}", stringify!(#ident));
            // 原函数逻辑（此处简化，实际需保留原函数体）
        }
    };

    TokenStream::from(expanded)
}

在其他 crate 中使用该宏：

use my_attr_macro::log_call;

#[log_call]  // 应用自定义属性宏
fn hello() {
    println!("Hello, world!");
}

fn main() {
    hello();  // 输出：Calling function: hello → Hello, world!
}