在 Rust 中，代码的灵活性和重用性是开发中的重要目标，而 宏（Macros） 是实现这一目标的强大工具。宏是 Rust 元编程（metaprogramming）的一部分，允许开发者在编译时生成代码，从而减少重复工作并提升灵活性。本章将从整体介绍宏的概念，探索其两种主要类型——声明式宏和过程宏，并详细讲解过程宏的三大子类：派生宏、属性式宏和函数式宏。

Rust的宏分为两类：

• 声明式宏（Declarative Macros）：通过 macro_rules! 定义，基于模式匹配和文本替换，简单易用但功能有限。
• 过程宏（Procedural Macros）：通过 Rust 代码操作抽象语法树（AST），包括派生宏、属性式宏和函数式宏，更强大但实现复杂。

宏的工作依赖于抽象语法树（AST），这是编译器将源代码解析成的一种树状结构，每个节点表示一个语法元素，如表达式、语句或函数声明。声明式宏直接替换文本，不涉及 AST 操作；过程宏则通过解析和修改AST生成代码。选择使用哪种宏取决于功能的复杂性和对类型安全的需求。

常见宏一览

Rust 提供了一些内置宏，作为日常开发中的实用工具。以下是几个常见示例：

fn main() {
    // println! - 输出文本
    println!("Processing data...");

    // vec! - 创建动态数组
    let numbers = vec![10, 20, 30];

    // assert! - 验证条件
    let value = 5;
    assert!(value > 0, "Value must be positive!");

    // format! - 生成格式化字符串
    let text = format!("Found {} items", numbers.len());
    println!("{}", text);
}

这些宏在编译时展开为具体代码，简化了常见任务的实现。接下来，我们深入两种宏的具体用法。

声明式宏 - 基于模式的文本替换

声明式宏使用 macro_rules! 定义，通过模式匹配生成代码。它不操作 AST，仅进行文本替换，适合简单的代码转换场景。

定义声明式宏

假设我们要创建一个宏 log_items，用于记录多个项：

macro_rules! log_items {
    ($item:expr, $count:expr) => {{
        for _ in 0..$count {
            println!("Item: {}", $item);
        }
    }};
}

fn main() {
    log_items!("box", 3);
    // 输出:
    // Item: box
    // Item: box
    // Item: box
}

这里，$item:expr 匹配一个表达式（如"box"），$count:expr 匹配次数，宏展开为一个 for 循环，直接嵌入代码。

多模式支持

声明式宏可以定义多个模式，适应不同输入：

macro_rules! log_items {
    ($item:expr, $count:expr) => {{
        for _ in 0..$count {
            println!("Item: {}", $item);
        }
    }};
    ($item:expr) => {{
        println!("Single item: {}", $item);
    }};
}

fn main() {
    log_items!("box", 2);
    log_items!("crate");
    // 输出:
    // Item: box
    // Item: box
    // Single item: crate
}

编译器根据参数数量选择匹配的模式，展开为相应代码。

处理可变参数

声明式宏支持不定数量的参数，通过 * 或 + 操作符实现：

macro_rules! sum_values {
    ($($value:expr),*) => {{
        let mut total = 0;
        $(
            total += $value;
        )*
        total
    }};
}

fn main() {
    let result = sum_values!(1, 2, 3, 4);
    println!("Sum: {}", result);// 输出: Sum: 10
}

$($value:expr),* 表示零个或多个表达式，展开时为每个值生成 total += $value。这使得宏能处理任意数量的输入。

过程宏

过程宏通过 Rust 代码处理 AST，提供更高的灵活性。它包括三种类型：派生宏、属性式宏和函数式宏，适用于复杂代码生成。

派生宏 - 自动实现特征

派生宏为类型自动实现特征，简化代码编写：

#[derive(Debug)]
struct Record {
    id: u32,
    name: String,
}

fn main() {
    let record = Record {
        id: 1,
        name: String::from("Item A"),
    };
    println!("{:?}", record); // 输出: Record { id: 1, name: "Item A" }
}

[derive(Debug)] 在编译时为 Record 追加 Debug 特征的实现。

自定义派生宏

以下是自定义派生宏Report的简化实现（需独立crate）：

extern crate proc_macro;
use proc_macro::TokenStream;
use quote::quote;
use syn;

#[proc_macro_derive(Report)]
pub fn report_derive(input: TokenStream) -> TokenStream {
    let ast = syn::parse(input).unwrap();
    let name = &ast.ident;
    let gen = quote! {
        impl Report for #name {
            fn report() {
                println!("Reporting: {}", stringify!(#name));
            }
        }
    };
    gen.into()
}

// 使用示例
#[derive(Report)]
struct Box;

#[derive(Report)]
struct Tray;

fn main() {
    Box::report();  // 输出: Reporting: Box
    Tray::report(); // 输出: Reporting: Tray
}

syn 解析输入的 AST，quote! 生成特征实现代码，#name 插入类型名称。派生宏在原有类型上追加功能。

属性式宏 - 增强代码行为

属性式宏通过 #[attr] 为代码添加自定义属性，扩展其功能：

#[proc_macro_attribute]
pub fn track_call(attr: TokenStream, item: TokenStream) -> TokenStream {
    let item_ast = syn::parse::<syn::ItemFn>(item.clone()).unwrap();
    let fn_name = &item_ast.sig.ident;
    let gen = quote! {
        #item_ast
        fn track_wrapper() {
            println!("Calling function: {}", stringify!(#fn_name));
            #fn_name();
        }
    };
    gen.into()
}

// 使用示例
#[track_call]
fn process_data() {
    println!("Data processed.");
}

fn main() {
    track_wrapper(); // 输出: Calling function: process_data \n Data processed.
}

attr 是属性参数（此处为空），item 是被标记的函数。宏生成一个包装函数，添加调用日志，增强了原函数行为。

函数式宏 - 灵活的代码生成

函数式宏通过 name!(...) 调用，像函数但在编译时生成代码：

#[proc_macro]
pub fn log_event(input: TokenStream) -> TokenStream {
    let input_str = input.to_string();
    let gen = quote! {
        println!("Event logged: {}", #input_str);
    };
    gen.into()
}

// 使用示例
fn main() {
    log_event!("system start");
    // 输出: Event logged: system start
}

input 是调用中的参数，宏生成简单的打印语句。相比声明式宏，函数式宏能用 Rust 逻辑处理输入，提供更大灵活性。

宏与函数的对比

宏和函数都是代码重用的工具，但区别显著。函数在运行时执行，参数类型和数量固定；宏在编译时展开，参数更灵活：

fn log_once() {
    println!("Logged!");
}

macro_rules! log_once {
    () => {
        println!("Logged!");
    };
}

fn main() {
    log_once();  // 函数调用
    log_once!(); // 宏展开
}

函数通过调用栈执行，宏直接嵌入代码，无运行时开销。宏还能处理可变参数和复杂逻辑，使其适用范围更广，但调试和理解成本较高。

灵活性示例

宏可以接受不定参数，而函数不行：

macro_rules! log_all {
    ($($msg:expr),*) => {
        $(
            println!("Log: {}", $msg);
        )*
    };
}

fn main() {
    log_all!("start", "process", "end");
    // 输出:
    // Log: start
    // Log: process
    // Log: end
}

这种能力让宏在生成动态代码时更具优势。

小结

• 宏是 Rust 元编程工具，在编译时生成代码，提升灵活性。
• 声明式宏通过 macro_rules! 进行模式匹配和文本替换，简单高效。
• 过程宏操作 AST，包括：
  • 派生宏为类型自动实现特征。
  • 属性式宏为代码添加自定义属性。
  • 函数式宏灵活生成代码。
• 宏与函数相比，编译时展开更灵活，但复杂度更高。