函数宏 Function-like
核心概念
函数式过程宏(function-like procedural macro)是过程宏的第三种形式,通过 macro_name!(...) 语法调用,看起来和声明宏一样,但背后是一个完整的 Rust 函数在编译时运行。它的函数签名是 (TokenStream) -> TokenStream,输入是括号内的所有 token,输出是替换宏调用的代码。
函数式过程宏比声明宏强大得多,因为它可以使用完整的 Rust 编程能力(条件判断、循环、字符串处理、甚至读取文件),而不局限于模式匹配。它适合实现自定义的 DSL(领域特定语言)、编译时代码验证、以及需要复杂逻辑的代码生成。
// === 函数式过程宏定义(过程宏 crate 侧)===
//
// use proc_macro::TokenStream;
//
// #[proc_macro]
// pub fn sql(input: TokenStream) -> TokenStream {
// let query = input.to_string();
// // 在编译时验证 SQL 语法
// // 生成类型安全的查询代码
// // ...
// todo!()
// }
//
// // 使用:
// let users = sql!(SELECT * FROM users WHERE age > 18);
// === 与声明宏的语法对比 ===
//
// 声明宏调用: vec![1, 2, 3]
// 函数式过程宏:sql!(SELECT * FROM users)
//
// 两者调用语法相同,都用 name!(...)
// 区别在于背后的实现方式不同
fn main() {
println!("函数式过程宏:name!(...) 语法,完整 Rust 编程能力");
}三种过程宏对比
| 特性 | 函数式过程宏 | 派生宏 | 属性宏 |
|---|---|---|---|
| 语法 | name!(...) | #[derive(Name)] | #[name] |
| 标注属性 | #[proc_macro] | #[proc_macro_derive] | #[proc_macro_attribute] |
| 输入参数 | 1 个 TokenStream | 1 个 TokenStream | 2 个 TokenStream |
| 可用位置 | 表达式、语句、项 | 类型定义上方 | 项上方 |
| 典型用途 | DSL、代码生成 | trait 实现 | 函数修饰 |
函数式过程宏的实现
// === 完整的函数式过程宏实现 ===
//
// // Cargo.toml
// // [lib]
// // proc-macro = true
// //
// // [dependencies]
// // syn = { version = "2", features = ["full"] }
// // quote = "1"
//
// use proc_macro::TokenStream;
// use quote::quote;
// use syn::{parse_macro_input, LitStr, Token, punctuated::Punctuated};
// use syn::parse::{Parse, ParseStream};
//
// // 自定义解析结构
// struct EnvConfig {
// pairs: Vec<(String, String)>,
// }
//
// impl Parse for EnvConfig {
// fn parse(input: ParseStream) -> syn::Result<Self> {
// let mut pairs = Vec::new();
// while !input.is_empty() {
// let key: syn::Ident = input.parse()?;
// input.parse::<Token![=]>()?;
// let value: LitStr = input.parse()?;
// pairs.push((key.to_string(), value.value()));
// if !input.is_empty() {
// input.parse::<Token![,]>()?;
// }
// }
// Ok(EnvConfig { pairs })
// }
// }
//
// #[proc_macro]
// pub fn env_config(input: TokenStream) -> TokenStream {
// let config = parse_macro_input!(input as EnvConfig);
//
// let insertions = config.pairs.iter().map(|(k, v)| {
// quote! { map.insert(#k.to_string(), #v.to_string()); }
// });
//
// let expanded = quote! {{
// let mut map = std::collections::HashMap::new();
// #(#insertions)*
// map
// }};
//
// TokenStream::from(expanded)
// }
//
// // 使用:
// let config = env_config!(
// HOST = "localhost",
// PORT = "8080",
// DEBUG = "true"
// );
fn main() {
println!("函数式过程宏可以定义自定义的解析规则");
}常见应用场景
// === 1. SQL 查询宏(编译时验证)===
//
// // 类似 sqlx 的 query! 宏
// let users = sqlx::query!(
// "SELECT id, name FROM users WHERE age > $1",
// 18
// ).fetch_all(&pool).await?;
//
// 编译时:连接数据库,验证 SQL 语法和类型
// === 2. 正则表达式编译时检查 ===
//
// // 类似 regex 的编译时检查版本
// let re = regex!(r"^\d{4}-\d{2}-\d{2}$");
// // 编译时检查正则语法是否合法
// === 3. JSON 字面量 ===
//
// let value = json!({
// "name": "Alice",
// "age": 30,
// "hobbies": ["reading", "coding"]
// });
// === 4. HTML 模板 ===
//
// let page = html! {
// <div class="container">
// <h1>{title}</h1>
// <p>{content}</p>
// </div>
// };
// === 5. 编译时格式化字符串检查 ===
// println! 和 format! 本身就是编译时检查参数的宏
fn main() {
// 标准库中的函数式宏
let v = vec![1, 2, 3]; // vec! 是声明宏
println!("hello {}", "world"); // println! 是声明宏
let s = format!("x = {}", 42); // format! 是声明宏
// 以下是过程宏(概念)
// let data = json!({"key": "value"}); // serde_json
// let query = sqlx::query!("SELECT 1"); // sqlx
println!("v = {:?}, s = {}", v, s);
}函数式过程宏 vs 声明宏
// 什么时候用函数式过程宏代替 macro_rules!?
// 用声明宏的场景:
// - 简单的模式替换
// - 不需要复杂逻辑
// - 不想增加编译依赖
macro_rules! simple_max {
($a:expr, $b:expr) => {
if $a > $b { $a } else { $b }
};
}
// 需要函数式过程宏的场景:
// - 需要编译时验证(如 SQL 语法、正则表达式)
// - 需要读取外部资源(文件、数据库)
// - 需要复杂的字符串处理
// - 需要自定义的解析语法
// - 声明宏的模式匹配无法表达的逻辑
fn main() {
println!("max(3, 7) = {}", simple_max!(3, 7));
println!("声明宏能解决的问题就用声明宏");
println!("需要编程逻辑时才用函数式过程宏");
}| 对比项 | 声明宏 (macro_rules!) | 函数式过程宏 |
|---|---|---|
| 定义方式 | 模式匹配 | Rust 函数 |
| 逻辑能力 | 递归 + 模式匹配 | 完整 Rust 编程 |
| 外部 IO | 不支持 | 支持(读文件、连数据库) |
| 编译依赖 | 无 | syn、quote 等 |
| 编译速度 | 快 | 较慢 |
| 定义位置 | 任意 crate | proc-macro crate |
| 调用语法 | name!(...) | name!(...) |
| 自定义解析 | 不支持 | 支持(syn Parse trait) |
基本示例
// 演示函数式过程宏的使用效果
// 模拟 serde_json 的 json! 宏效果
// 实际的 serde_json::json! 是声明宏,这里用于概念说明
use std::collections::HashMap;
// 用声明宏模拟简单的键值对构建
macro_rules! config {
($($key:literal : $value:expr),* $(,)?) => {{
let mut map = HashMap::new();
$(
map.insert($key.to_string(), format!("{}", $value));
)*
map
}};
}
// 模拟编译时检查的 assert_static 宏
macro_rules! static_assert {
($cond:expr) => {
const _: () = assert!($cond);
};
}
// 编译时断言
static_assert!(std::mem::size_of::<u32>() == 4);
static_assert!(std::mem::size_of::<u64>() == 8);
fn main() {
let cfg = config! {
"host": "localhost",
"port": 8080,
"debug": true,
};
for (key, value) in &cfg {
println!("{} = {}", key, value);
}
println!("\n编译时断言全部通过");
println!("u32 大小 = {} 字节", std::mem::size_of::<u32>());
println!("u64 大小 = {} 字节", std::mem::size_of::<u64>());
}常见问题
问题一:函数式过程宏可以在表达式位置使用吗?
可以。函数式过程宏可以在语句、表达式、项等几乎所有宏调用位置使用。这比派生宏和属性宏更灵活。
问题二:函数式过程宏和声明宏的调用语法完全一样吗?
是的,都用 name!(...) 语法。从调用者的角度看不出区别。区别在于定义方式和背后的实现机制。编译器通过宏的定义来区分。
问题三:函数式过程宏可以访问文件系统吗?
可以。过程宏在编译时运行的是完整的 Rust 代码,可以读取文件、访问环境变量、甚至发网络请求。但要注意这会影响构建的确定性和可移植性。
问题四:函数式过程宏和声明宏同名会冲突吗?
同一作用域内不能有同名的宏,无论是声明宏还是过程宏。不同 crate 的同名宏通过路径区分。
适用场景
- DSL 设计:SQL、HTML、CSS、正则表达式等嵌入式语言
- 编译时验证:在编译阶段检查数据的正确性
- 代码生成:根据外部配置生成代码
- 类型安全 API:如 sqlx 的编译时类型检查查询
- 嵌入外部数据:将文件内容编译时嵌入代码
注意事项
- 用
#[proc_macro]标注,函数签名(TokenStream) -> TokenStream - 必须定义在 proc-macro crate 中
- 可以通过
syn::Parsetrait 实现自定义解析 - 编译时 IO 操作会影响构建的确定性
- 优先考虑声明宏,只在需要编程能力时使用函数式过程宏
- 错误信息需要手动提供精确的 Span
总结
函数式过程宏通过 name!(...) 语法调用,用 #[proc_macro] 标注定义,签名为 (TokenStream) -> TokenStream。它拥有完整的 Rust 编程能力,可以实现声明宏无法完成的复杂逻辑,包括自定义解析语法、编译时验证、读取外部文件等。典型应用包括 SQL 编译时检查(sqlx)、JSON 字面量(serde_json)、正则表达式预编译等 DSL 场景。与声明宏相比,函数式过程宏更强大但需要独立 crate 和额外依赖,编译也更慢。能用声明宏解决的场景应优先使用声明宏。