属性宏 Attribute
核心概念
属性宏(attribute macro)是过程宏的第二种形式,通过 #[macro_name] 或 #[macro_name(...)] 语法使用。与派生宏不同,属性宏可以完全替换被标注的项——它既能修改原始代码,也能生成全新的代码。属性宏常用于 Web 框架的路由定义、测试框架的标注、日志/追踪的自动注入等场景。
属性宏的函数签名是 (TokenStream, TokenStream) -> TokenStream,第一个参数是属性括号内的参数(如 #[route(GET, "/")] 中的 GET, "/"),第二个参数是被标注的项(函数、结构体等),返回值是替换后的完整代码。
// === 属性宏定义(过程宏 crate 侧)===
//
// use proc_macro::TokenStream;
//
// #[proc_macro_attribute]
// pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream {
// // attr: 属性参数,如 GET, "/"
// // item: 被标注的函数定义
// // 返回: 替换后的代码
//
// // 解析属性参数
// let args = attr.to_string();
//
// // 解析被标注的函数
// let input = parse_macro_input!(item as syn::ItemFn);
// let fn_name = &input.sig.ident;
//
// let expanded = quote! {
// // 保留原始函数
// #input
//
// // 追加路由注册代码
// inventory::submit! {
// Route::new(#args, #fn_name)
// }
// };
//
// TokenStream::from(expanded)
// }
// === 使用侧 ===
// #[route(GET, "/")]
// fn index() -> String {
// "Hello, World!".to_string()
// }
fn main() {
println!("属性宏通过 #[macro_name] 使用");
println!("它接收两个 TokenStream:属性参数 + 被标注的项");
}属性宏 vs 派生宏
| 特性 | 属性宏 | 派生宏 |
|---|---|---|
| 语法 | #[name] / #[name(...)] | #[derive(Name)] |
| 可修改原始项 | 是 | 否(只能追加) |
| 输入参数 | 两个 TokenStream | 一个 TokenStream |
| 可标注的项 | 函数、结构体、impl 块、模块等 | 结构体、枚举、联合体 |
| 标注属性 | #[proc_macro_attribute] | #[proc_macro_derive] |
| 典型用途 | 路由、条件编译、AOP | trait 自动实现 |
常见使用模式
// === 模式1:包装函数(不修改原始函数,添加前后逻辑)===
//
// #[proc_macro_attribute]
// pub fn timed(_attr: TokenStream, item: TokenStream) -> TokenStream {
// let input = parse_macro_input!(item as syn::ItemFn);
// let fn_name = &input.sig.ident;
// let fn_name_str = fn_name.to_string();
// let block = &input.block;
// let sig = &input.sig;
// let vis = &input.vis;
// let attrs = &input.attrs;
//
// let expanded = quote! {
// #(#attrs)*
// #vis #sig {
// let __start = std::time::Instant::now();
// let __result = (|| #block)();
// println!("{} 耗时: {:?}", #fn_name_str, __start.elapsed());
// __result
// }
// };
//
// TokenStream::from(expanded)
// }
//
// // 使用
// #[timed]
// fn heavy_computation() -> i32 {
// (0..1_000_000).sum()
// }
// === 模式2:条件编译 ===
//
// #[proc_macro_attribute]
// pub fn debug_only(_attr: TokenStream, item: TokenStream) -> TokenStream {
// // 在 release 模式下移除函数
// if cfg!(not(debug_assertions)) {
// return TokenStream::new(); // 返回空 = 删除原始项
// }
// item // debug 模式下保留原始项
// }
// === 模式3:修改函数签名 ===
//
// #[proc_macro_attribute]
// pub fn async_handler(_attr: TokenStream, item: TokenStream) -> TokenStream {
// let mut input = parse_macro_input!(item as syn::ItemFn);
// // 将同步函数转为异步函数
// input.sig.asyncness = Some(syn::token::Async::default());
// quote!(#input).into()
// }
fn main() {
println!("属性宏可以包装、修改或删除被标注的项");
}实际框架中的属性宏
// 各大框架中属性宏的使用方式
// === tokio 的 #[tokio::main] ===
// 将 async main 函数包装在 tokio 运行时中
//
// #[tokio::main]
// async fn main() {
// println!("异步主函数");
// }
//
// 展开后大致等同于:
// fn main() {
// tokio::runtime::Runtime::new()
// .unwrap()
// .block_on(async {
// println!("异步主函数");
// })
// }
// === actix-web 的路由 ===
//
// #[get("/users/{id}")]
// async fn get_user(path: web::Path<u32>) -> impl Responder {
// format!("User {}", path.into_inner())
// }
// === test 属性 ===
// 标准库的 #[test] 本质上也是属性宏
//
// #[test]
// fn it_works() {
// assert_eq!(2 + 2, 4);
// }
// === tracing 的 #[instrument] ===
//
// #[tracing::instrument]
// async fn handle_request(id: u32) -> String {
// // 自动添加 span 和参数记录
// format!("处理请求 {}", id)
// }
fn main() {
// 标准属性的使用示例
#[allow(dead_code)]
fn unused() {}
#[cfg(target_os = "windows")]
fn platform_specific() {
println!("Windows 专用");
}
#[cfg(target_os = "windows")]
platform_specific();
println!("属性宏是框架构建的核心工具");
}基本示例
// 展示属性宏使用效果的完整示例
// 模拟一个简单的路由系统(不使用实际的过程宏,用手动方式演示效果)
struct Route {
method: &'static str,
path: &'static str,
handler: fn() -> String,
}
// 如果有属性宏,可以这样写:
// #[route(GET, "/")]
// fn index() -> String { "首页".to_string() }
//
// 属性宏会自动注册到路由表中
// 手动模拟属性宏展开后的效果
fn index() -> String { "首页".to_string() }
fn about() -> String { "关于".to_string() }
fn api_users() -> String { "用户列表".to_string() }
fn get_routes() -> Vec<Route> {
vec![
Route { method: "GET", path: "/", handler: index },
Route { method: "GET", path: "/about", handler: about },
Route { method: "GET", path: "/api/users", handler: api_users },
]
}
fn handle_request(method: &str, path: &str) -> String {
let routes = get_routes();
for route in &routes {
if route.method == method && route.path == path {
return (route.handler)();
}
}
"404 Not Found".to_string()
}
fn main() {
println!("{}", handle_request("GET", "/"));
println!("{}", handle_request("GET", "/about"));
println!("{}", handle_request("GET", "/api/users"));
println!("{}", handle_request("POST", "/unknown"));
}常见问题
问题一:属性宏返回空 TokenStream 会怎样?
被标注的项会被完全删除。这可以用来实现条件编译——在某些条件下移除整个函数或模块。
问题二:属性宏可以标注在任何项上吗?
可以标注在函数、结构体、枚举、impl 块、模块、extern 块、trait 定义等几乎所有项上。具体支持哪些取决于宏的实现。
问题三:属性宏的第一个参数(attr)可以为空吗?
可以。当使用 #[my_attr](没有括号)时,attr 参数是空的 TokenStream。当使用 #[my_attr(args)] 时,attr 包含括号内的 token。
问题四:属性宏和内置属性有什么区别?
内置属性(如 #[test]、#[cfg]、#[allow])由编译器直接处理。自定义属性宏由用户定义的过程宏函数处理。使用方式相同,但内置属性不需要额外的 crate。
适用场景
- Web 框架路由:
#[get("/")]、#[post("/users")] - 异步运行时:
#[tokio::main]、#[async_std::main] - 测试框架:
#[test]、#[bench] - 日志/追踪:
#[instrument]、#[traced] - 条件编译:根据条件移除或修改代码
- AOP(面向切面):自动添加前后处理逻辑
注意事项
- 属性宏用
#[proc_macro_attribute]标注 - 函数签名是
(TokenStream, TokenStream) -> TokenStream - 第一个参数是属性参数,第二个是被标注的项
- 返回空 TokenStream 会删除原始项
- 如果要保留原始项,必须在输出中包含它
- 属性宏的错误信息需要手动提供精确的 Span
总结
属性宏通过 #[name] 或 #[name(...)] 语法使用,是过程宏中最灵活的一种。它接收两个 TokenStream(属性参数和被标注的项),可以完全替换、修改或删除原始代码。属性宏广泛用于 Web 框架路由(#[get("/")])、异步运行时(#[tokio::main])、日志追踪(#[instrument])等场景。与派生宏不同,属性宏可以标注在几乎任何项上,且能修改原始代码。返回空 TokenStream 会删除被标注的项,如果要保留必须在输出中包含原始代码。