第19章 宏编程

宏是Rust中一种强大的元编程工具，它允许开发者在编译期间生成和操作代码。Rust的宏系统提供了在抽象语法树（AST）级别操作代码的能力，这使得宏比普通函数更加强大和灵活。本章将深入探讨Rust宏的各个方面，从基础概念到高级应用。

19.1 宏的基础知识

在深入具体类型的宏之前，让我们先建立对宏系统的基本理解，包括宏的工作原理、与函数的区别以及宏在Rust生态系统中的重要性。

宏与函数的区别

虽然宏和函数都用于代码重用，但它们在本质上有重要区别：

// 函数：在运行时执行，有固定的参数类型和数量
fn add(a: i32, b: i32) -> i32 {
    a + b
}

// 宏：在编译时展开，可以接受可变参数和多种语法结构
macro_rules! add_macro {
    ($a:expr, $b:expr) => {
        $a + $b
    };
}

// 宏可以处理函数无法处理的情况
macro_rules! create_function {
    ($func_name:ident) => {
        fn $func_name() {
            println!("You called {}", stringify!($func_name));
        }
    };
}

fn demonstrate_macro_vs_function() {
    // 函数调用
    let result1 = add(2, 3);
    println!("Function result: {}", result1);
    
    // 宏展开
    let result2 = add_macro!(2, 3);
    println!("Macro result: {}", result2);
    
    // 宏可以创建新函数
    create_function!(hello_macro);
    hello_macro();
    
    // 宏可以接受可变数量的参数
    println!("Sum: {}", add_macro!(1, 2, 3, 4)); // 这行会编译错误，展示宏的限制
    // 但我们可以设计支持可变参数的宏...
}

宏的工作原理

宏在编译过程的早期阶段——在语法分析和类型检查之前——被展开。这个过程可以分为几个步骤：

1. 词法分析：源代码被分解为标记（tokens）
2. 宏解析：识别宏调用并解析宏参数
3. 宏展开：根据宏定义生成新的代码
4. 语法分析：将展开后的代码解析为AST
5. 后续编译：类型检查、代码生成等

// 让我们通过一个具体例子理解宏展开过程
macro_rules! debug_print {
    ($($arg:expr),*) => {
        {
            println!("[DEBUG] {}:{}", file!(), line!());
            println!("[DEBUG] {}", format!($($arg),*));
        }
    };
}

fn demonstrate_macro_expansion() {
    let x = 42;
    let name = "Alice";
    
    // 这个宏调用...
    debug_print!("x = {}, name = {}", x, name);
    
    // ...在编译时会展开为：
    // {
    //     println!("[DEBUG] {}:{}", file!(), line!());
    //     println!("[DEBUG] {}", format!("x = {}, name = {}", x, name));
    // }
    
    // 注意：file!()和line!()也是内置宏，它们会在展开时被替换为具体值
}

宏的卫生性

Rust的宏系统是卫生的（hygienic），这意味着宏中引入的标识符不会意外地与调用处的代码冲突。

macro_rules! hygienic_example {
    () => {
        let x = 42;  // 这个x在宏内部定义
        println!("Inside macro: x = {}", x);
    };
}

fn demonstrate_hygiene() {
    let x = 100;  // 这个x在外部作用域
    
    hygienic_example!();  // 宏内部的x不会影响外部的x
    
    println!("Outside macro: x = {}", x);  // 仍然输出100
    
    // 但是，宏可以故意与外部交互
    macro_rules! intentional_capture {
        ($var:ident) => {
            $var = $var * 2;  // 这里故意使用外部变量
        };
    }
    
    let mut y = 10;
    intentional_capture!(y);
    println!("After intentional capture: y = {}", y);  // 输出20
}

内置宏

Rust提供了一系列有用的内置宏，它们在标准库和日常编程中广泛使用：

fn demonstrate_builtin_macros() {
    // 编译时信息宏
    println!("File: {}", file!());
    println!("Line: {}", line!());
    println!("Column: {}", column!());
    println!("Module path: {}", module_path!());
    
    // 字符串化相关宏
    let expression = 2 + 2;
    println!("Stringified: {}", stringify!(2 + 2));
    println!("Format string: {}", format!("The value is {}", expression));
    println!("Concatenated: {}", concat!("Hello", " ", "World"));
    
    // 断言宏
    assert!(2 + 2 == 4, "Math is broken!");
    assert_eq!(2 + 2, 4, "Math is really broken!");
    assert_ne!(2 + 2, 5, "This should not happen");
    
    // 编译时检查
    const _: () = {
        // 编译时断言
        assert!(std::mem::size_of::<i32>() == 4);
    };
    
    // 环境变量宏
    if let Ok(profile) = std::env::var("PROFILE") {
        println!("Build profile: {}", profile);
    }
    
    // 包含文件宏
    // let config = include_str!("config.toml");
    // let binary_data = include_bytes!("data.bin");
    
    println!("Built-in macros demonstration complete");
}

宏的优缺点

在决定是否使用宏时，需要考虑其优缺点：

优点：

• 零成本抽象：宏在编译时展开，运行时没有额外开销
• 语法扩展：可以创建领域特定语言（DSL）
• 代码生成：减少重复代码
• 编译时计算：可以在编译时执行复杂计算

缺点：

• 编译时间：宏展开会增加编译时间
• 调试困难：错误信息可能不够清晰
• 复杂性：宏代码可能难以理解和维护
• 过度使用：可能导致代码难以理解

// 宏的合适使用场景示例

// 1. 减少重复代码
macro_rules! create_getters {
    ($struct_name:ident { $($field:ident : $field_type:ty),* }) => {
        impl $struct_name {
            $(
                pub fn $field(&self) -> $field_type {
                    self.$field
                }
            )*
        }
    };
}

struct Person {
    name: String,
    age: u32,
}

create_getters!(Person { name: String, age: u32 });

// 2. 创建领域特定语言
macro_rules! html {
    ($name:ident { $($content:tt)* }) => {
        // HTML DSL实现
    };
}

// 3. 编译时验证
macro_rules! checked_division {
    ($a:expr, $b:expr) => {
        {
            if $b == 0 {
                panic!("Division by zero!");
            }
            $a / $b
        }
    };
}

fn demonstrate_macro_benefits() {
    let person = Person {
        name: "Alice".to_string(),
        age: 30,
    };
    
    println!("Name: {}, Age: {}", person.name(), person.age());
    
    let result = checked_division!(10, 2);
    println!("Division result: {}", result);
    
    // 这会panic
    // let bad_result = checked_division!(10, 0);
}

19.2 声明宏用于通用元编程

声明宏（declarative macros）是Rust中最常见的宏类型，使用macro_rules!语法定义。它们通过模式匹配和模板替换来工作，非常适合处理重复的代码模式。

基本语法和结构

声明宏由三部分组成：宏名称、模式分支和展开模板。

// 最简单的声明宏
macro_rules! say_hello {
    () => {  // 模式分支
        println!("Hello, world!");  // 展开模板
    };
}

// 带参数的宏
macro_rules! greet {
    ($name:expr) => {
        println!("Hello, {}!", $name);
    };
}

// 多个模式分支
macro_rules! describe {
    (number $n:expr) => {
        println!("This is a number: {}", $n);
    };
    (text $t:expr) => {
        println!("This is text: {}", $t);
    };
    ($other:expr) => {
        println!("This is something else: {:?}", $other);
    };
}

fn demonstrate_basic_macros() {
    say_hello!();
    greet!("Alice");
    describe!(number 42);
    describe!(text "hello");
    describe!(vec![1, 2, 3]);
}

元变量类型

元变量是宏模式中用于匹配和捕获代码片段的特殊变量。Rust支持多种元变量类型：

macro_rules! demonstrate_metavariables {
    // ident: 标识符（变量名、函数名等）
    ($func_name:ident) => {
        fn $func_name() {
            println!("Function {} called", stringify!($func_name));
        }
    };
    
    // expr: 表达式
    ($expression:expr) => {
        println!("Expression: {} = {}", stringify!($expression), $expression);
    };
    
    // ty: 类型
    ($type_name:ty) => {
        println!("Type: {}", stringify!($type_name));
    };
    
    // pat: 模式
    ($pattern:pat) => {
        println!("Pattern: {}", stringify!($pattern));
    };
    
    // path: 路径（模块路径、类型路径等）
    ($path:path) => {
        println!("Path: {}", stringify!($path));
    };
    
    // tt: 标记树（单个标记或括号内的标记组）
    ($token:tt) => {
        println!("Token: {}", stringify!($token));
    };
    
    // item: 项（函数、结构体、模块等）
    ($item:item) => {
        $item
    };
    
    // block: 代码块
    ($block:block) => {
        println!("Block result: {:?}", $block);
    };
    
    // stmt: 语句
    ($stmt:stmt) => {
        $stmt
    };
    
    // literal: 字面量
    ($literal:literal) => {
        println!("Literal: {}", $literal);
    };
}

fn use_metavariable_macros() {
    demonstrate_metavariables!(some_function);  // ident
    demonstrate_metavariables!(2 + 2);         // expr
    demonstrate_metavariables!(i32);           // ty
    demonstrate_metavariables!(Some(x));       // pat
    demonstrate_metavariables!(std::vec::Vec); // path
    demonstrate_metavariables!(*);             // tt
    demonstrate_metavariables!(fn dummy() {}); // item
    demonstrate_metavariables!({ 1 + 1 });     // block
    demonstrate_metavariables!(let x = 5;);    // stmt
    demonstrate_metavariables!(42);            // literal
}

重复模式

重复模式是声明宏最强大的特性之一，允许处理可变数量的参数。

// 基本重复模式
macro_rules! vector {
    ($($element:expr),*) => {
        {
            let mut v = Vec::new();
            $(
                v.push($element);
            )*
            v
        }
    };
    
    ($($element:expr,)*) => {
        vector!($($element),*)
    };
}

// 多种重复分隔符
macro_rules! hash_map {
    ($($key:expr => $value:expr),*) => {
        {
            use std::collections::HashMap;
            let mut map = HashMap::new();
            $(
                map.insert($key, $value);
            )*
            map
        }
    };
}

// 嵌套重复
macro_rules! matrix {
    ($([$($element:expr),*]),*) => {
        {
            let mut matrix = Vec::new();
            $(
                let mut row = Vec::new();
                $(
                    row.push($element);
                )*
                matrix.push(row);
            )*
            matrix
        }
    };
}

// 重复修饰符：*（0次或多次）、+（1次或多次）、?（0次或1次）
macro_rules! optional_debug {
    ($($arg:expr),* $(,)?) => {  // 尾随逗号可选
        $(
            println!("{:?}", $arg);
        )*
    };
}

fn demonstrate_repetition() {
    // 创建向量
    let v1 = vector!(1, 2, 3, 4, 5);
    let v2 = vector!(1, 2, 3, 4, 5,);  // 支持尾随逗号
    println!("Vectors: {:?}, {:?}", v1, v2);
    
    // 创建HashMap
    let map = hash_map!(
        "a" => 1,
        "b" => 2,
        "c" => 3
    );
    println!("HashMap: {:?}", map);
    
    // 创建矩阵
    let m = matrix!(
        [1, 2, 3],
        [4, 5, 6],
        [7, 8, 9]
    );
    println!("Matrix: {:?}", m);
    
    // 可选调试
    optional_debug!(1, "hello", vec![1, 2, 3]);
    optional_debug!();  // 无参数也可以
}

高级模式匹配

声明宏支持复杂的模式匹配，包括嵌套模式和多个分支。

// 复杂模式匹配
macro_rules! complex_match {
    // 匹配函数定义
    (fn $name:ident($($param:ident : $param_type:ty),*) -> $return_type:ty $body:block) => {
        fn $name($($param: $param_type),*) -> $return_type $body
    };
    
    // 匹配结构体定义
    (struct $name:ident { $($field:ident : $field_type:ty),* }) => {
        struct $name {
            $($field: $field_type),*
        }
    };
    
    // 匹配方法实现
    (impl $trait_name:ident for $type_name:ty {
        $($method:item)*
    }) => {
        impl $trait_name for $type_name {
            $($method)*
        }
    };
    
    // 匹配属性
    (#[$attr:meta] $item:item) => {
        #[$attr]
        $item
    };
}

// 使用复杂模式
complex_match! {
    fn add(a: i32, b: i32) -> i32 {
        a + b
    }
}

complex_match! {
    struct Point {
        x: f64,
        y: f64
    }
}

trait Display {
    fn display(&self);
}

complex_match! {
    impl Display for Point {
        fn display(&self) {
            println!("Point({}, {})", self.x, self.y);
        }
    }
}

complex_match! {
    #[derive(Debug)]
    struct DebuggablePoint {
        x: f64,
        y: f64
    }
}

fn use_complex_macros() {
    let result = add(2, 3);
    println!("Add result: {}", result);
    
    let point = Point { x: 1.0, y: 2.0 };
    point.display();
    
    let debug_point = DebuggablePoint { x: 3.0, y: 4.0 };
    println!("Debug point: {:?}", debug_point);
}

递归宏

宏可以递归调用自身，这允许处理任意复杂度的输入。

// 递归宏示例：计算表达式
macro_rules! calculate {
    // 基础情况：单个数字
    ($x:literal) => { $x };
    
    // 加法
    ($a:tt + $b:tt) => {
        calculate!($a) + calculate!($b)
    };
    
    // 减法
    ($a:tt - $b:tt) => {
        calculate!($a) - calculate!($b)
    };
    
    // 乘法
    ($a:tt * $b:tt) => {
        calculate!($a) * calculate!($b)
    };
    
    // 除法
    ($a:tt / $b:tt) => {
        calculate!($a) / calculate!($b)
    };
    
    // 括号表达式
    (($inner:tt)) => {
        calculate!($inner)
    };
}

// 递归宏处理JSON样式的数据结构
macro_rules! json {
    // 空对象
    ({}) => {
        std::collections::HashMap::new()
    };
    
    // 带字段的对象
    ({ $($key:literal : $value:tt),* }) => {
        {
            let mut map = std::collections::HashMap::new();
            $(
                map.insert($key.to_string(), json!($value));
            )*
            map
        }
    };
    
    // 数组
    ([ $($element:tt),* ]) => {
        {
            let mut vec = Vec::new();
            $(
                vec.push(json!($element));
            )*
            vec
        }
    };
    
    // 字面量
    ($literal:literal) => {
        $literal.to_string()
    };
}

fn demonstrate_recursive_macros() {
    // 计算表达式
    let result = calculate!((2 + 3) * (4 - 1));
    println!("Calculation result: {}", result);
    
    // 创建JSON样式数据
    let data = json!({
        "name": "Alice",
        "age": "30",
        "hobbies": ["reading", "swimming"],
        "address": {
            "street": "123 Main St",
            "city": "Wonderland"
        }
    });
    
    println!("JSON data: {:?}", data);
}

宏的卫生性和标识符捕获

虽然Rust宏默认是卫生的，但有时我们需要故意捕获外部标识符。

// 卫生宏示例
macro_rules! hygienic_macro {
    () => {
        let local_var = 42;
        println!("Local var: {}", local_var);
    };
}

// 故意捕获外部变量的宏
macro_rules! capturing_macro {
    ($var:ident) => {
        $var = $var + 1;
    };
}

// 使用$crate确保在宏定义crate外也能正常工作
macro_rules! use_crate {
    () => {
        $crate::some_function()
    };
}

fn some_function() {
    println!("Function from crate root");
}

fn demonstrate_hygiene_and_capture() {
    let mut x = 10;
    
    // 卫生宏不会影响外部变量
    hygienic_macro!();
    // println!("{}", local_var); // 错误：local_var不存在
    
    // 捕获宏可以修改外部变量
    capturing_macro!(x);
    println!("x after capture: {}", x);
    
    // 使用$crate
    use_crate!();
}

19.3 过程宏用于自定义derive

过程宏（procedural macros）是更强大的宏类型，它们像函数一样操作Rust代码。过程宏分为三种：自定义derive宏、类属性宏和类函数宏。让我们从自定义derive宏开始。

过程宏项目设置

过程宏必须在独立的proc-macro crate中定义。

首先创建过程宏crate的Cargo.toml：

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

[lib]
proc-macro = true

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

然后在lib.rs中开始编写过程宏：

// src/lib.rs
extern crate proc_macro;

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

// 简单的自定义derive宏
#[proc_macro_derive(HelloMacro)]
pub fn hello_macro_derive(input: TokenStream) -> TokenStream {
    // 解析输入为DeriveInput
    let input = parse_macro_input!(input as DeriveInput);
    
    // 获取类型名称
    let name = &input.ident;
    
    // 生成实现代码
    let expanded = quote! {
        impl HelloMacro for #name {
            fn hello_macro() {
                println!("Hello, Macro! My name is {}!", stringify!(#name));
            }
        }
    };
    
    // 返回生成的代码
    TokenStream::from(expanded)
}

在使用crate的Cargo.toml中添加依赖：

[dependencies]
my_proc_macros = { path = "../my_proc_macros" }

然后使用宏：

use my_proc_macros::HelloMacro;

trait HelloMacro {
    fn hello_macro();
}

#[derive(HelloMacro)]
struct Pancakes;

fn main() {
    Pancakes::hello_macro(); // 输出: Hello, Macro! My name is Pancakes!
}

高级自定义derive宏

让我们创建更复杂的自定义derive宏，处理结构体字段和属性。

// 在过程宏crate中
use syn::{Data, Fields, Attribute};
use quote::quote;

// 为结构体生成builder方法
#[proc_macro_derive(Builder)]
pub fn builder_derive(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    
    let name = &input.ident;
    let builder_name = syn::Ident::new(&format!("{}Builder", name), name.span());
    
    // 处理结构体字段
    let fields = if let Data::Struct(data_struct) = &input.data {
        if let Fields::Named(fields_named) = &data_struct.fields {
            &fields_named.named
        } else {
            panic!("Builder only works on structs with named fields");
        }
    } else {
        panic!("Builder only works on structs");
    };
    
    // 生成builder结构体的字段
    let builder_fields = fields.iter().map(|field| {
        let field_name = &field.ident;
        let field_type = &field.ty;
        quote! {
            #field_name: std::option::Option<#field_type>
        }
    });
    
    // 生成setter方法
    let setter_methods = fields.iter().map(|field| {
        let field_name = &field.ident;
        let field_type = &field.ty;
        quote! {
            pub fn #field_name(mut self, value: #field_type) -> Self {
                self.#field_name = Some(value);
                self
            }
        }
    });
    
    // 生成build方法
    let build_checks = fields.iter().map(|field| {
        let field_name = &field.ident;
        quote! {
            #field_name: self.#field_name.take().ok_or_else(|| format!("field '{}' not set", stringify!(#field_name)))?
        }
    });
    
    let expanded = quote! {
        impl #name {
            pub fn builder() -> #builder_name {
                #builder_name::default()
            }
        }
        
        #[derive(Default)]
        pub struct #builder_name {
            #(#builder_fields),*
        }
        
        impl #builder_name {
            #(#setter_methods)*
            
            pub fn build(self) -> Result<#name, String> {
                Ok(#name {
                    #(#build_checks),*
                })
            }
        }
    };
    
    TokenStream::from(expanded)
}

使用这个builder宏：

use my_proc_macros::Builder;

#[derive(Builder)]
struct User {
    name: String,
    age: u32,
    email: String,
}

fn main() {
    let user = User::builder()
        .name("Alice".to_string())
        .age(30)
        .email("alice@example.com".to_string())
        .build()
        .unwrap();
    
    println!("User: {} ({}), {}", user.name, user.age, user.email);
}

处理枚举的自定义derive宏

自定义derive宏也可以用于枚举。

// 在过程宏crate中
use syn::{Data, Variant};

// 为枚举生成信息方法
#[proc_macro_derive(EnumInfo)]
pub fn enum_info_derive(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    
    let name = &input.ident;
    
    let variants = if let Data::Enum(data_enum) = &input.data {
        &data_enum.variants
    } else {
        panic!("EnumInfo can only be derived for enums");
    };
    
    // 获取变体名称
    let variant_names: Vec<_> = variants.iter()
        .map(|variant| &variant.ident)
        .collect();
    
    // 生成变体数量
    let variant_count = variants.len();
    
    let expanded = quote! {
        impl #name {
            pub fn variants() -> &'static [&'static str] {
                &[#(stringify!(#variant_names)),*]
            }
            
            pub fn variant_count() -> usize {
                #variant_count
            }
            
            pub fn from_str(s: &str) -> Option<Self> {
                match s {
                    #(
                        stringify!(#variant_names) => Some(Self::#variant_names),
                    )*
                    _ => None,
                }
            }
        }
    };
    
    TokenStream::from(expanded)
}

使用枚举宏：

use my_proc_macros::EnumInfo;

#[derive(EnumInfo, Debug)]
Color {
    Red,
    Green,
    Blue,
}

fn main() {
    println!("Color variants: {:?}", Color::variants());
    println!("Variant count: {}", Color::variant_count());
    
    if let Some(color) = Color::from_str("Red") {
        println!("Parsed color: {:?}", color);
    }
}

带属性的自定义derive宏

自定义derive宏可以处理属性，允许更灵活的代码生成。

// 在过程宏crate中
use syn::{Attribute, Meta, NestedMeta};

// 解析属性辅助函数
fn find_attr_value(attrs: &[Attribute], attr_name: &str) -> Option<String> {
    for attr in attrs {
        if let Meta::List(meta_list) = &attr.meta {
            if meta_list.path.get_ident().map(|i| i.to_string()) == Some(attr_name.to_string()) {
                // 解析属性内容
                let nested = meta_list.parse_args_with(|input: syn::parse::ParseStream| {
                    input.parse::<syn::LitStr>()
                }).ok()?;
                
                return Some(nested.value());
            }
        }
    }
    None
}

// 带属性的自定义derive宏
#[proc_macro_derive(Greeting, attributes(greet_message))]
pub fn greeting_derive(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    
    let name = &input.ident;
    
    // 从属性中获取自定义消息
    let message = find_attr_value(&input.attrs, "greet_message")
        .unwrap_or_else(|| "Hello".to_string());
    
    let expanded = quote! {
        impl #name {
            pub fn greet(&self) {
                println!("{} from {}!", #message, stringify!(#name));
            }
        }
    };
    
    TokenStream::from(expanded)
}

使用带属性的宏：

use my_proc_macros::Greeting;

#[derive(Greeting)]
#[greet_message = "Hi there"]
struct Person;

#[derive(Greeting)]  // 使用默认消息
struct Animal;

fn main() {
    let person = Person;
    let animal = Animal;
    
    person.greet();  // 输出: Hi there from Person!
    animal.greet();  // 输出: Hello from Animal!
}

19.4 类属性宏和类函数宏

除了自定义derive宏，Rust还有类属性宏和类函数宏，它们提供了不同的代码生成方式。

类属性宏

类属性宏可以附加到任何项上，而不仅仅是结构体和枚举。

// 在过程宏crate中
use syn::{ItemFn, AttributeArgs, NestedMeta, Lit};

// 简单的类属性宏：测量函数执行时间
#[proc_macro_attribute]
pub fn timed(attr: TokenStream, item: TokenStream) -> TokenStream {
    let args = parse_macro_input!(attr as AttributeArgs);
    let mut function = parse_macro_input!(item as ItemFn);
    
    let function_name = &function.sig.ident;
    
    // 解析属性参数（可选的消息）
    let message = if let Some(NestedMeta::Lit(Lit::Str(lit_str))) = args.first() {
        lit_str.value()
    } else {
        format!("Function {} took", function_name)
    };
    
    // 获取函数体
    let function_block = &function.block;
    
    // 生成新的函数体
    let new_block = quote! {
        {
            use std::time::Instant;
            let start = Instant::now();
            let result = (|| #function_block)();
            let duration = start.elapsed();
            println!("{} {:?}", #message, duration);
            result
        }
    };
    
    // 替换函数体
    function.block = syn::parse2(new_block).unwrap();
    
    TokenStream::from(quote! { #function })
}

使用类属性宏：

use my_proc_macros::timed;

#[timed]
fn expensive_operation() -> i32 {
    std::thread::sleep(std::time::Duration::from_millis(100));
    42
}

#[timed("Custom timing message")]
fn another_operation() -> i32 {
    std::thread::sleep(std::time::Duration::from_millis(50));
    24
}

fn main() {
    let result1 = expensive_operation();
    let result2 = another_operation();
    println!("Results: {}, {}", result1, result2);
}

类函数宏

类函数宏看起来像函数调用，但它们在编译时操作标记。

// 在过程宏crate中
use syn::parse::{Parse, ParseStream};
use syn::{Token, Ident, LitStr};
use proc_macro2::Span;

// 解析SQL查询的简单结构
struct SqlQuery {
    query: String,
    params: Vec<Ident>,
}

impl Parse for SqlQuery {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let query: LitStr = input.parse()?;
        
        let mut params = Vec::new();
        while !input.is_empty() {
            input.parse::<Token![,]>()?;
            let param: Ident = input.parse()?;
            params.push(param);
        }
        
        Ok(SqlQuery {
            query: query.value(),
            params,
        })
    }
}

// 类函数宏：创建类型安全的SQL查询
#[proc_macro]
pub fn sql(input: TokenStream) -> TokenStream {
    let sql_query = parse_macro_input!(input as SqlQuery);
    
    let query = sql_query.query;
    let params = sql_query.params;
    
    // 生成查询结构体
    let expanded = quote! {
        {
            // 创建查询结构体
            struct SqlQuery {
                query: String,
                params: Vec<String>,
            }
            
            impl SqlQuery {
                fn new() -> Self {
                    Self {
                        query: #query.to_string(),
                        params: Vec::new(),
                    }
                }
                
                fn execute(&self) {
                    println!("Executing: {}", self.query);
                    if !self.params.is_empty() {
                        println!("With parameters: {:?}", self.params);
                    }
                }
            }
            
            let mut query = SqlQuery::new();
            #(
                query.params.push(format!("{:?}", #params));
            )*
            query
        }
    };
    
    TokenStream::from(expanded)
}

使用类函数宏：

use my_proc_macros::sql;

fn main() {
    let name = "Alice";
    let age = 30;
    
    let query = sql!("SELECT * FROM users WHERE name = ? AND age > ?", name, age);
    query.execute();
}

高级过程宏：编译时验证

过程宏可以在编译时执行复杂的验证。

// 在过程宏crate中
use syn::{Fields, Type, Path};

// 检查字段是否实现特定trait的辅助函数
fn field_implements_trait(field_type: &Type, trait_name: &str) -> bool {
    // 在实际实现中，这里会有更复杂的检查逻辑
    // 这里简化为检查类型名称
    if let Type::Path(type_path) = field_type {
        if let Some(segment) = type_path.path.segments.last() {
            return segment.ident == "String" && trait_name == "Display";
        }
    }
    false
}

// 验证结构体宏
#[proc_macro_derive(ValidatedStruct)]
pub fn validated_struct_derive(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    
    let name = &input.ident;
    
    let fields = if let syn::Data::Struct(data_struct) = &input.data {
        if let Fields::Named(fields_named) = &data_struct.fields {
            &fields_named.named
        } else {
            panic!("ValidatedStruct only works on structs with named fields");
        }
    } else {
        panic!("ValidatedStruct only works on structs");
    };
    
    // 为每个字段生成验证逻辑
    let validation_checks: Vec<_> = fields.iter().map(|field| {
        let field_name = &field.ident;
        let field_type = &field.ty;
        
        // 根据字段类型生成不同的验证逻辑
        if field_implements_trait(field_type, "Display") {
            quote! {
                if self.#field_name.is_empty() {
                    return Err(format!("Field '{}' cannot be empty", stringify!(#field_name)));
                }
            }
        } else {
            quote! {
                // 对其他类型字段的默认验证
            }
        }
    }).collect();
    
    let expanded = quote! {
        impl #name {
            pub fn validate(&self) -> Result<(), String> {
                #(#validation_checks)*
                Ok(())
            }
        }
    };
    
    TokenStream::from(expanded)
}

使用验证宏：

use my_proc_macros::ValidatedStruct;

#[derive(ValidatedStruct)]
struct User {
    name: String,
    age: i32,
}

fn main() {
    let valid_user = User {
        name: "Alice".to_string(),
        age: 30,
    };
    
    let invalid_user = User {
        name: "".to_string(),  // 空名字
        age: 30,
    };
    
    println!("Valid user: {:?}", valid_user.validate());
    println!("Invalid user: {:?}", invalid_user.validate());
}

19.5 宏的调试与测试

调试宏可能很困难，因为错误可能发生在宏展开期间或展开后的代码中。让我们探讨一些有效的调试和测试策略。

宏调试技巧

// 在过程宏crate中添加调试支持
#[proc_macro_derive(DebuggableMacro)]
pub fn debuggable_derive(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    
    // 在编译时打印调试信息
    println!("[MACRO DEBUG] Processing struct: {}", input.ident);
    
    let name = &input.ident;
    
    let expanded = quote! {
        impl #name {
            pub fn macro_debug_info() -> &'static str {
                "This struct was processed by DebuggableMacro"
            }
        }
    };
    
    // 也可以打印生成的代码
    // println!("[MACRO DEBUG] Generated code: {}", expanded);
    
    TokenStream::from(expanded)
}

// 使用compile_error!进行编译时错误报告
#[proc_macro_derive(CheckedDerive)]
pub fn checked_derive(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    
    // 检查是否在结构体上使用
    if let syn::Data::Enum(_) = &input.data {
        return syn::Error::new_spanned(
            input.ident,
            "CheckedDerive can only be used on structs, not enums"
        )
        .to_compile_error()
        .into();
    }
    
    let name = &input.ident;
    let expanded = quote! {
        impl #name {
            pub fn checked_method() -> bool {
                true
            }
        }
    };
    
    TokenStream::from(expanded)
}

测试过程宏

为过程宏编写测试非常重要。

// 在过程宏crate的tests目录中
// tests/test_builder.rs

#[cfg(test)]
mod tests {
    use my_proc_macros::Builder;
    use syn::{parse_quote, ItemStruct};
    use quote::quote;
    
    #[test]
    fn test_builder_generation() {
        // 测试输入结构体
        let input: ItemStruct = parse_quote! {
            struct User {
                name: String,
                age: u32,
            }
        };
        
        // 应用builder宏
        let expanded = my_proc_macros::builder_derive(quote! { #input });
        
        // 检查生成的代码是否可以编译
        // 在实际测试中，我们会解析生成的代码并验证其结构
        assert!(!expanded.is_empty());
    }
    
    #[test]
    fn test_builder_usage() {
        // 这个测试在实际使用crate中编写
        // 验证builder模式正常工作
    }
}

// 在过程宏crate的src/lib.rs中添加测试
#[cfg(test)]
mod tests {
    use super::*;
    use proc_macro2::TokenStream;
    use syn::ItemStruct;
    
    #[test]
    fn test_hello_macro() {
        let input: TokenStream = quote! {
            struct TestStruct;
        };
        
        let output = hello_macro_derive(input);
        assert!(!output.is_empty());
        
        // 可以进一步解析输出并验证其内容
        let output_str = output.to_string();
        assert!(output_str.contains("impl HelloMacro for TestStruct"));
    }
}

使用cargo-expand调试宏

cargo-expand是一个非常有用的工具，可以查看宏展开后的代码。

安装cargo-expand：

cargo install cargo-expand

使用示例：

cargo expand

宏的文档和最佳实践

为宏编写良好的文档非常重要。

/// 一个用于创建getter方法的宏
///
/// # 示例
///
/// ```rust
/// # use my_proc_macros::create_getters;
/// #[create_getters]
/// struct Person {
///     name: String,
///     age: u32,
/// }
///
/// let person = Person { name: "Alice".to_string(), age: 30 };
/// assert_eq!(person.get_name(), "Alice");
/// assert_eq!(person.get_age(), 30);
/// ```
#[proc_macro_attribute]
pub fn create_getters(attr: TokenStream, item: TokenStream) -> TokenStream {
    // 实现...
    item
}

总结

宏是Rust中非常强大的元编程工具，它们允许开发者在编译时生成和操作代码。本章涵盖了：

1. 宏的基础知识：宏与函数的区别、工作原理、卫生性和内置宏
2. 声明宏：使用macro_rules!进行模式匹配和代码生成
3. 过程宏：自定义derive宏、类属性宏和类函数宏
4. 高级技巧：递归宏、属性处理、编译时验证
5. 调试和测试：宏的调试技巧和测试策略

宏的正确使用可以大大减少重复代码、提高类型安全性并创建领域特定语言。然而，宏也应该谨慎使用，因为它们会增加代码的复杂性和编译时间。

掌握宏编程是成为Rust高级开发者的重要一步，它让你能够创建更强大、更灵活的抽象，同时保持Rust的性能和安全性优势。