函数宏 Function-like ​

核心概念 ​

函数式过程宏(function-like procedural macro)是过程宏的第三种形式,通过 macro_name!(...) 语法调用,看起来和声明宏一样,但背后是一个完整的 Rust 函数在编译时运行。它的函数签名是 (TokenStream) -> TokenStream,输入是括号内的所有 token,输出是替换宏调用的代码。

函数式过程宏比声明宏强大得多,因为它可以使用完整的 Rust 编程能力(条件判断、循环、字符串处理、甚至读取文件),而不局限于模式匹配。它适合实现自定义的 DSL(领域特定语言)、编译时代码验证、以及需要复杂逻辑的代码生成。

rust
// === 函数式过程宏定义(过程宏 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 个 TokenStream1 个 TokenStream2 个 TokenStream
可用位置表达式、语句、项类型定义上方项上方
典型用途DSL、代码生成trait 实现函数修饰

函数式过程宏的实现 ​

rust
// === 完整的函数式过程宏实现 ===
//
// // 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!("函数式过程宏可以定义自定义的解析规则");
}

常见应用场景 ​

rust
// === 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 声明宏 ​

rust
// 什么时候用函数式过程宏代替 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 等
编译速度快较慢
定义位置任意 crateproc-macro crate
调用语法name!(...)name!(...)
自定义解析不支持支持(syn Parse trait)

基本示例 ​

rust
// 演示函数式过程宏的使用效果

// 模拟 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::Parse trait 实现自定义解析
  • 编译时 IO 操作会影响构建的确定性
  • 优先考虑声明宏,只在需要编程能力时使用函数式过程宏
  • 错误信息需要手动提供精确的 Span

总结 ​

函数式过程宏通过 name!(...) 语法调用,用 #[proc_macro] 标注定义,签名为 (TokenStream) -> TokenStream。它拥有完整的 Rust 编程能力,可以实现声明宏无法完成的复杂逻辑,包括自定义解析语法、编译时验证、读取外部文件等。典型应用包括 SQL 编译时检查(sqlx)、JSON 字面量(serde_json)、正则表达式预编译等 DSL 场景。与声明宏相比,函数式过程宏更强大但需要独立 crate 和额外依赖,编译也更慢。能用声明宏解决的场景应优先使用声明宏。