Rust 宏

宏是 Rust 中强大的元编程工具，允许您编写可以生成其他代码的代码。本教程将深入介绍 Rust 宏的各种类型、使用方法和实际应用场景。

🎯 内容概述

通过本章节，您将了解和掌握：

理解宏的概念和用途
掌握声明宏（declarative macros）的编写
了解过程宏（procedural macros）的基本概念
学会在实际项目中使用宏

📖 什么是宏？

宏的定义

Rust 宏（Macros）是一种元编程技术，它允许您编写可以生成其他代码的代码（编写代码时创建自定义语法扩展）。与函数不同，宏在编译时展开，可以接受可变数量的参数，并且可以操作 Rust 的语法结构。

宏在 Rust 中有两种类型：声明式宏（Declarative Macros）和过程宏（Procedural Macros）。

本文主要介绍声明式宏。

宏与函数的区别

特性	函数	宏
展开时机	运行时调用	编译时展开
参数数量	固定参数	可变参数
类型检查	严格类型检查	模式匹配
性能	运行时开销	零运行时开销
复杂度	相对简单	可能很复杂

宏的优势

代码生成：自动生成重复性代码
零成本抽象：编译时展开，无运行时开销
语法扩展：创建特定领域的语言（DSL）
类型安全：在编译时进行检查

🔧 声明宏（Declarative Macros）

声明宏使用 macro_rules! 语法定义，是最常见的宏类型。

基础语法

macro_rules! 宏名 {
    (模式) => {
        // 展开代码
    };
}

简单示例：打印调试信息

macro_rules! debug_print {
    ($x:expr) => {
        println!("调试信息: {} = {:?}", stringify!($x), $x);
    };
}

fn main() {
    let 数字 = 42;
    let 名字 = "张三";
    
    debug_print!(数字);    // 输出: 调试信息: 数字 = 42
    debug_print!(名字);    // 输出: 调试信息: 名字 = "张三"
}

Vec 宏的实现解析

让我们详细分析标准库中 vec! 宏的简化实现：

macro_rules! vec {
    // 空 vec 的情况
    () => {
        Vec::new()
    };
    
    // 带初始值的情况
    ( $( $x:expr ),* ) => {
        {
            let mut 临时向量 = Vec::new();
            $(
                临时向量.push($x);
            )*
            临时向量
        }
    };
    
    // 重复值的情况：vec![0; 5]
    ( $x:expr; $n:expr ) => {
        vec![0; $n].into_iter().map(|_| $x).collect()
    };
}

fn main() {
    let 空向量: Vec<i32> = vec![];
    let 数字向量 = vec![1, 2, 3, 4, 5];
    let 重复向量 = vec!["你好"; 3];
    
    println!("空向量: {:?}", 空向量);
    println!("数字向量: {:?}", 数字向量);
    println!("重复向量: {:?}", 重复向量);
}

模式匹配详解

常用标识符类型

标识符	描述	示例
`$x:expr`	表达式	`42`, `变量名`, `函数调用()`
`$x:ident`	标识符	变量名、函数名
`$x:ty`	类型	`i32`, `String`, `Vec<T>`
`$x:pat`	模式	`Some(x)`, `Ok(_)`
`$x:stmt`	语句	`let x = 5;`
`$x:block`	代码块	`{ ... }`
`$x:item`	项目	函数、结构体定义
`$x:tt`	token 树	任何 token 序列

重复模式

macro_rules! 创建函数 {
    (
        $函数名:ident(
            $($参数名:ident: $参数类型:ty),*
        ) -> $返回类型:ty {
            $($语句:stmt;)*
        }
    ) => {
        fn $函数名($($参数名: $参数类型),*) -> $返回类型 {
            $($语句;)*
        }
    };
}

创建函数!(
    计算和(a: i32, b: i32) -> i32 {
        let 结果 = a + b;
        return 结果;
    }
);

fn main() {
    let 和 = 计算和(10, 20);
    println!("10 + 20 = {}", 和);
}

高级声明宏示例

创建哈希映射的宏

use std::collections::HashMap;

macro_rules! hashmap {
    ($($键:expr => $值:expr),* $(,)?) => {
        {
            let mut 映射 = HashMap::new();
            $(
                映射.insert($键, $值);
            )*
            映射
        }
    };
}

fn main() {
    let 学生成绩 = hashmap!{
        "张三" => 85,
        "李四" => 92,
        "王五" => 78,
    };
    
    for (姓名, 成绩) in &学生成绩 {
        println!("{}: {}", 姓名, 成绩);
    }
}

条件编译宏

macro_rules! 平台特定代码 {
    (windows => $windows_code:block, unix => $unix_code:block) => {
        #[cfg(target_os = "windows")]
        $windows_code
        
        #[cfg(any(target_os = "linux", target_os = "macos"))]
        $unix_code
    };
}

fn main() {
    平台特定代码!(
        windows => {
            println!("在 Windows 系统上运行");
            // Windows 特定代码
        },
        unix => {
            println!("在 Unix 系统上运行");
            // Unix 特定代码
        }
    );
}

🔬 过程宏（Procedural Macros）

过程宏是更高级的宏类型，它们实际上是函数，可以操作 Rust 代码的抽象语法树（AST）。

过程宏的类型

函数式宏（Function-like macros）
派生宏（Derive macros）
属性宏（Attribute macros）

派生宏示例

// 在 Cargo.toml 中添加依赖
// [dependencies]
// serde = { version = "1.0", features = ["derive"] }

use serde::{Serialize, Deserialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct 用户 {
    姓名: String,
    年龄: u32,
    邮箱: String,
}

fn main() {
    let 用户1 = 用户 {
        姓名: "李明".to_string(),
        年龄: 25,
        邮箱: "liming@example.com".to_string(),
    };
    
    // Debug trait 自动实现
    println!("用户信息: {:?}", 用户1);
    
    // Clone trait 自动实现
    let 用户2 = 用户1.clone();
    
    // Serialize trait 自动实现
    let json = serde_json::to_string(&用户1).unwrap();
    println!("JSON: {}", json);
}

自定义派生宏

要创建自定义派生宏，需要创建一个过程宏 crate：

# Cargo.toml
[lib]
proc-macro = true

[dependencies]
syn = "1.0"
quote = "1.0"
proc-macro2 = "1.0"

// src/lib.rs
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

#[proc_macro_derive(打招呼)]
pub fn 打招呼_derive(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    let name = &input.ident;
    
    let expanded = quote! {
        impl #name {
            pub fn 打招呼(&self) -> String {
                format!("你好，我是 {}！", stringify!(#name))
            }
        }
    };
    
    TokenStream::from(expanded)
}

使用自定义派生宏：

use my_macro_crate::打招呼;

#[derive(打招呼)]
struct 学生 {
    姓名: String,
}

#[derive(打招呼)]
struct 老师 {
    学科: String,
}

fn main() {
    let 学生1 = 学生 { 姓名: "小明".to_string() };
    let 老师1 = 老师 { 学科: "数学".to_string() };
    
    println!("{}", 学生1.打招呼());  // 输出: 你好，我是 学生！
    println!("{}", 老师1.打招呼());  // 输出: 你好，我是 老师！
}

🛠️ 实际应用场景

1. 日志宏

macro_rules! 日志 {
    (错误, $($arg:tt)*) => {
        eprintln!("[错误] {}", format!($($arg)*));
    };
    (警告, $($arg:tt)*) => {
        println!("[警告] {}", format!($($arg)*));
    };
    (信息, $($arg:tt)*) => {
        println!("[信息] {}", format!($($arg)*));
    };
}

fn main() {
    日志!(信息, "应用程序启动");
    日志!(警告, "内存使用率: {}%", 85);
    日志!(错误, "连接数据库失败: {}", "超时");
}

2. 测试宏

macro_rules! 断言相等 {
    ($left:expr, $right:expr) => {
        if $left != $right {
            panic!(
                "断言失败: {} != {}\n  左值: {:?}\n  右值: {:?}",
                stringify!($left),
                stringify!($right),
                $left,
                $right
            );
        } else {
            println!("✓ 测试通过: {} == {}", stringify!($left), stringify!($right));
        }
    };
}

fn main() {
    let a = 5;
    let b = 5;
    let c = 10;
    
    断言相等!(a, b);  // 测试通过
    // 断言相等!(a, c);  // 会触发 panic
}

3. 配置宏

macro_rules! 配置 {
    {
        数据库: {
            主机: $db_host:expr,
            端口: $db_port:expr,
            用户: $db_user:expr,
        },
        服务器: {
            端口: $server_port:expr,
            工作线程: $workers:expr,
        }
    } => {
        pub struct 应用配置 {
            pub 数据库主机: String,
            pub 数据库端口: u16,
            pub 数据库用户: String,
            pub 服务器端口: u16,
            pub 工作线程数: usize,
        }
        
        impl 应用配置 {
            pub fn 新建() -> Self {
                Self {
                    数据库主机: $db_host.to_string(),
                    数据库端口: $db_port,
                    数据库用户: $db_user.to_string(),
                    服务器端口: $server_port,
                    工作线程数: $workers,
                }
            }
        }
    };
}

配置! {
    数据库: {
        主机: "localhost",
        端口: 5432,
        用户: "admin",
    },
    服务器: {
        端口: 8080,
        工作线程: 4,
    }
}

fn main() {
    let 配置 = 应用配置::新建();
    println!("数据库连接: {}:{}", 配置.数据库主机, 配置.数据库端口);
    println!("服务器端口: {}", 配置.服务器端口);
}

⚠️ 宏的最佳实践

1. 命名约定

宏名使用 snake_case 或中文命名
避免与标准库宏重名
使用描述性的名称

2. 错误处理

macro_rules! 安全除法 {
    ($a:expr, $b:expr) => {
        {
            if $b == 0 {
                panic!("除数不能为零！");
            }
            $a / $b
        }
    };
}

fn main() {
    let 结果1 = 安全除法!(10, 2);  // 正常
    println!("10 / 2 = {}", 结果1);
    
    // let 结果2 = 安全除法!(10, 0);  // 会 panic
}

3. 文档化

/// 创建一个包含指定元素的向量
/// 
/// # 示例
/// ```
/// let v = my_vec![1, 2, 3];
/// assert_eq!(v, vec![1, 2, 3]);
/// ```
macro_rules! my_vec {
    ($($x:expr),* $(,)?) => {
        {
            let mut v = Vec::new();
            $(v.push($x);)*
            v
        }
    };
}

🎯 常见陷阱和解决方案

1. 卫生性问题

// 问题：变量名冲突
macro_rules! 有问题的宏 {
    ($x:expr) => {
        {
            let temp = $x * 2;  // 可能与用户代码中的 temp 冲突
            temp
        }
    };
}

// 解决方案：使用唯一的变量名
macro_rules! 安全的宏 {
    ($x:expr) => {
        {
            let __宏_内部_temp = $x * 2;  // 使用前缀避免冲突
            __宏_内部_temp
        }
    };
}

2. 多次求值问题

// 问题：表达式可能被多次求值
macro_rules! 有副作用的宏 {
    ($x:expr) => {
        $x + $x  // $x 被求值两次
    };
}

// 解决方案：先求值再使用
macro_rules! 安全求值 {
    ($x:expr) => {
        {
            let 值 = $x;  // 只求值一次
            值 + 值
        }
    };
}

fn 计数器() -> i32 {
    static mut COUNT: i32 = 0;
    unsafe {
        COUNT += 1;
        COUNT
    }
}

fn main() {
    // 有副作用的宏会调用 计数器() 两次
    // let 结果1 = 有副作用的宏!(计数器());
    
    // 安全求值只调用一次
    let 结果2 = 安全求值!(计数器());
    println!("结果: {}", 结果2);
}

📚 总结

本教程介绍了 Rust 宏的核心概念和实际应用：

主要内容回顾

宏的基本概念：理解宏与函数的区别
声明宏：使用 macro_rules! 创建代码生成模板
过程宏：更高级的宏类型，可操作 AST
实际应用：日志、测试、配置等场景
最佳实践：避免常见陷阱，编写安全的宏

关键要点

宏在编译时展开，提供零成本抽象
声明宏适合简单的代码生成
过程宏提供更强大的功能，但复杂度更高
编写宏时要注意卫生性和多次求值问题

::: tip 实践建议

从简单的声明宏开始练习
阅读标准库宏的源码学习技巧
在实际项目中逐步应用宏来减少重复代码
为复杂宏编写详细的文档和测试 :::

::: warning 注意事项

宏会增加编译时间
过度使用宏可能降低代码可读性
宏的错误信息通常比较难以理解
调试宏代码比较困难 :::

继续学习：下一章 - Rust 智能指针

#Rust 宏

#🎯 内容概述

#📖 什么是宏？

#宏的定义

#宏与函数的区别

#宏的优势

#🔧 声明宏（Declarative Macros）

#基础语法

#简单示例：打印调试信息

#Vec 宏的实现解析

#模式匹配详解

#常用标识符类型

#重复模式

#高级声明宏示例

#创建哈希映射的宏

#条件编译宏

#🔬 过程宏（Procedural Macros）

#过程宏的类型

#派生宏示例

#自定义派生宏

#🛠️ 实际应用场景

#1. 日志宏

#2. 测试宏

#3. 配置宏

#⚠️ 宏的最佳实践

#1. 命名约定

#2. 错误处理

#3. 文档化

#🎯 常见陷阱和解决方案

#1. 卫生性问题

#2. 多次求值问题

#📚 总结

#主要内容回顾

#关键要点