Rust 推荐使用宏而非普通函数的场景

先铺垫核心底层差异，再分场景逐条讲「为什么宏能做、函数做不到/做起来极差」，附带代码对比。

一、宏与函数的本质区别（理解场景的前提）

维度	函数	宏
执行时机	运行期执行，参数是运行时值，类型固定	编译期展开，输入是语法树（token/抽象语法），能操作代码结构
类型约束	参数必须是确定类型，泛型函数仍受类型系统、生命周期、Trait 约束	不限制输入语法，可以接收任意代码片段、标识符、类型、语句块
作用域与语法访问	函数内部无法获取调用处的标识符、行号、文件名、局部变量名	宏可以捕获调用上下文全部语法信息
代码生成能力	函数只能执行逻辑、返回值，不能生成新结构体、impl、match 分支、常量	宏可以批量生成大量重复代码，消除模板冗余

核心结论： 只要需求需要操作「代码本身、编译期信息、动态生成语法结构」，函数无法胜任，必须用宏。

二、场景 1：捕获编译期元信息（文件、行号、模块路径）

需求特征

日志、断言、错误追踪，需要打印代码所在文件名、行号、列号、模块路径。

函数做不到的原因

函数参数只能传运行时值，调用函数时无法自动把 file!() line!() 注入，必须手动传，极其繁琐。

宏实现（标准库示例 `assert!` `dbg!`）

rust 复制代码

// 宏实现，自动捕获上下文
macro_rules! my_assert {
    ($cond:expr, $msg:literal) => {
        if !$cond {
            panic!(
                "断言失败：{} \n文件:{} 行:{}",
                $msg, file!(), line!()
            )
        }
    };
}

// 使用，无需手动传文件行号
my_assert!(1 + 1 == 3, "加法出错");

如果改用函数：

rust 复制代码

fn my_assert_func(cond: bool, msg: &str, file: &str, line: u32) {
    if !cond { panic!("{} {}:{}", msg, file, line); }
}

// 每次调用都要手动附加元信息，冗余爆炸
my_assert_func(1 + 1 == 3, "加法出错", file!(), line!());

典型标准库宏

dbg!、assert! / debug_assert!、todo!、unreachable!、panic!

三、场景 2：可变数量参数（任意个表达式、无固定签名）

需求特征

格式化打印、批量收集表达式、多参数日志，参数个数不固定。

函数局限

Rust 函数不支持真正可变参数：

只能用数组/vec 传参，需要手动包裹 vec![a, b, c]
无法直接接收零散表达式，语法累赘

宏优势

宏可通过 $(...),* 匹配任意数量输入 token，原生支持变长参数。

rust 复制代码

// 简易 println 复刻宏
macro_rules! print_log {
    ($($arg:expr),*) => {
        println!("{}", format!($($arg),*));
    };
}

// 任意个参数直接传入，不用容器包裹
print_log!("num={}", 123, ", str={}", "test");

函数方案对比（极其啰嗦）：

rust 复制代码

fn print_log_func(args: &[&dyn std::fmt::Display]) {
    for a in args { print!("{}", a); }
}

print_log_func(&[&"num=", &123, &", str=", &"test"]);

典型场景

日志库、格式化输出、批量求值宏。

四、场景 3：生成新语法结构（批量生成代码）

需求特征

批量生成结构体、枚举、impl 实现、常量、match 分支、测试用例。

函数完全不可能做到：函数运行时无法新增代码定义。

示例 1：批量定义常量

rust 复制代码

macro_rules! define_consts {
    ($($name:ident = $val:expr),*) => {
        $(
            const $name: u32 = $val;
        )*
    };
}

// 一行生成多个常量
define_consts!(A = 1, B = 2, C = 3);

示例 2：批量实现 trait

rust 复制代码

trait Show {
    fn show(&self);
}

macro_rules! impl_show {
    ($($ty:ty),*) => {
        $(
            impl Show for $ty {
                fn show(&self) {
                    println!("值: {:?}", self);
                }
            }
        )*
    };
}

// 一次性给多个类型实现 trait
impl_show!(u8, u16, i32, String);

典型使用场景

绑定 FFI C 枚举/结构体
数据库 ORM 批量生成模型代码
测试框架批量生成测试函数
状态机批量生成 match 分支

五、场景 4：操作标识符（变量名、类型名、函数名）

需求特征

动态拼接标识符、基于输入名字生成新变量/函数/字段。

函数完全无法实现：函数只能操作值，不能操作「变量名字符串标识符」，标识符是编译期语法概念，运行时不存在。

宏示例：拼接标识符

rust 复制代码

macro_rules! make_pair {
    ($name:ident, $val:expr) => {
        // 拼接 ident：生成 xxx_val 变量
        let concat_id = stringify!($name);
        let $name = $val;
        paste::paste! {
            let [<$name _val>] = $val * 2;
            println!("{}_val = {}", concat_id, [<$name _val>]);
        }
    };
}

make_pair!(num, 10);
// 展开后生成 num 和 num_val 两个局部变量

常见依赖：paste 宏库用于标识符拼接。

业务场景

自动生成 get/set 方法
解析配置自动生成对应变量
解析协议字段自动生成访问器

六、场景 5：接收语法块（任意语句、match、loop、impl 等完整代码）

需求特征

自定义 DSL（领域特定语言）、封装执行上下文、作用域守卫、异步块包装。

函数参数只能是表达式 ，不能直接接收 { ... } 语句块并拆解内部语法；宏原生支持捕获任意代码块 token。

示例：自定义作用域计时器 DSL

rust 复制代码

use std::time::Instant;

macro_rules! time_block {
    ($name:literal, $block:block) => {
        let start = Instant::now();
        $block;
        let dur = start.elapsed();
        println!("{} 耗时: {:?}", $name, dur);
    };
}

// 直接传入任意代码块，函数做不到优雅接收整块语句
time_block!("计算循环", {
    let mut s = 0;
    for i in 0..10000 { s += i; }
});

经典标准库案例

vec![1, 2, 3]、if let 相关辅助宏、tokio::select!、async_std::task 块宏、测试 #[test] 配套块宏。

七、场景 6：条件编译 / 条件生成代码（编译期分支）

需求

根据输入常量、feature 开关、类型特征，决定是否生成某段代码。

函数只能运行时分支判断，无用代码仍会编译；宏在编译期直接丢弃不需要的代码，零开销。

rust 复制代码

macro_rules! debug_only {
    ($block:block) => {
        #[cfg(debug_assertions)]
        $block
    };
}

debug_only!({
    println!("仅调试模式打印");
});

函数写法对比：

rust 复制代码

fn debug_only_func(block: impl Fn()) {
    if cfg!(debug_assertions) { block(); }
}

// 闭包代码永远参与编译，release 模式只是不执行，不会被裁剪干净
debug_only_func(|| println!("仅调试模式打印"));

八、场景 7：零开销抽象，消除运行时间接层

函数的隐性开销

普通函数调用：栈帧、跳转
泛型函数会单例膨胀，但仍有调用
闭包传参存在 trait 对象/动态分发开销

宏的优势

编译期原地展开代码，无函数调用、无间接跳转，完全零运行时成本。适合高频执行、性能敏感的底层工具：

位运算工具宏
嵌入式硬件寄存器访问宏
高频日志打点（release 下直接消除日志代码）

九、场景 8：突破类型系统 / 生命周期限制（延迟类型解析）

函数的所有参数、返回值类型必须在调用处完全确定，受生命周期、借用规则即时检查；宏是先展开再做类型检查，可以先组装代码再让编译器校验，解决很多泛型/生命周期复杂场景。

典型案例

serde 序列化派生宏 --- 根据结构体字段自动生成复杂 impl，手动函数/泛型无法实现
async 相关宏 --- 把同步代码块转换为 Future 状态机，函数无法改写语法结构
反射式派生宏 --- derive_builder、thiserror 等

十、场景总结

必选宏的场景汇总

需要文件名、行号、模块等编译期元信息
变长参数，不想手动套数组/容器
批量生成结构体、impl、常量、测试函数等代码
需要操作、拼接变量标识符
自定义 DSL，接收完整语句块、match/loop/impl 语法
编译期条件裁剪代码，零运行时开销
派生/ORM/FFI 自动代码生成
改写底层语法（async、错误枚举、状态机）

优先函数（普通/泛型函数）的场景

仅处理运行时值，不需要操作代码语法
逻辑复杂、需要单独单元测试（宏难测试、报错晦涩）
不需要代码生成，固定参数数量
需要递归运行时逻辑、捕获环境闭包
公共库对外简单工具（宏报错提示差，调试成本高）

补充：宏的短板（不要滥用）

编译器报错可读性差
难以单元测试
过度使用会让代码逻辑分散、难以阅读
调试器无法单步进入宏展开代码

Rust 规范：能用函数绝不写宏，只有函数完全无法实现需求时才使用宏。

Rust 推荐使用宏而非普通函数的场景

一、宏与函数的本质区别（理解场景的前提）

二、场景 1：捕获编译期元信息（文件、行号、模块路径）

需求特征

函数做不到的原因

宏实现（标准库示例 assert! dbg!）

典型标准库宏

三、场景 2：可变数量参数（任意个表达式、无固定签名）

需求特征

函数局限

宏优势

典型场景

四、场景 3：生成新语法结构（批量生成代码）

需求特征

示例 1：批量定义常量

示例 2：批量实现 trait

典型使用场景

五、场景 4：操作标识符（变量名、类型名、函数名）

需求特征

宏示例：拼接标识符

业务场景

六、场景 5：接收语法块（任意语句、match、loop、impl 等完整代码）

需求特征

示例：自定义作用域计时器 DSL

经典标准库案例

七、场景 6：条件编译 / 条件生成代码（编译期分支）

需求

八、场景 7：零开销抽象，消除运行时间接层

函数的隐性开销

宏的优势

九、场景 8：突破类型系统 / 生命周期限制（延迟类型解析）

典型案例

十、场景总结

必选宏的场景汇总

优先函数（普通/泛型函数）的场景

补充：宏的短板（不要滥用）

宏实现（标准库示例 `assert!` `dbg!`）