属性宏 Attribute ​

核心概念 ​

属性宏(attribute macro)是过程宏的第二种形式,通过 #[macro_name] 或 #[macro_name(...)] 语法使用。与派生宏不同,属性宏可以完全替换被标注的项——它既能修改原始代码,也能生成全新的代码。属性宏常用于 Web 框架的路由定义、测试框架的标注、日志/追踪的自动注入等场景。

属性宏的函数签名是 (TokenStream, TokenStream) -> TokenStream,第一个参数是属性括号内的参数(如 #[route(GET, "/")] 中的 GET, "/"),第二个参数是被标注的项(函数、结构体等),返回值是替换后的完整代码。

rust
// === 属性宏定义(过程宏 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]
典型用途路由、条件编译、AOPtrait 自动实现

常见使用模式 ​

rust
// === 模式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!("属性宏可以包装、修改或删除被标注的项");
}

实际框架中的属性宏 ​

rust
// 各大框架中属性宏的使用方式

// === 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!("属性宏是框架构建的核心工具");
}

基本示例 ​

rust
// 展示属性宏使用效果的完整示例

// 模拟一个简单的路由系统(不使用实际的过程宏,用手动方式演示效果)

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 会删除被标注的项,如果要保留必须在输出中包含原始代码。