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

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

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

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

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

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

需求特征

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

函数做不到的原因

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

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

// 宏实现，自动捕获上下文
macro_rules! my_assert {
($cond:expr, $msg:literal) => {
if !$cond {
panic!(
"断言失败：{} n文件:{} 行:{}",
$msg, file!(), line!()
)
}
};
}
// 使用，无需手动传文件行号
my_assert!(1 + 1 == 3, "加法出错");

如果改用函数：

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，原生支持变长参数。

// 简易 println 复刻宏
macro_rules! print_log {
($($arg:expr),*) => {
println!("{}", format!($($arg),*));
};
}
// 任意个参数直接传入，不用容器包裹
print_log!("num={}", 123, ", str={}", "test");

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

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：批量定义常量

macro_rules! define_consts {
($($name:ident = $val:expr),*) => {
$(
const $name: u32 = $val;
)*
};
}
// 一行生成多个常量
define_consts!(A = 1, B = 2, C = 3);

示例 2：批量实现 trait

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：操作标识符（变量名、类型名、函数名）

需求特征

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

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

宏示例：拼接标识符

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

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 开关、类型特征，决定是否生成某段代码。

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

macro_rules! debug_only {
($block:block) => {
#[cfg(debug_assertions)]
$block
};
}
debug_only!({
println!("仅调试模式打印");
});

函数写法对比：

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 规范：能用函数绝不写宏，只有函数完全无法实现需求时才使用宏。