#![...] 与外层属性 #[...] 的语法、作用范围与使用位置。#[name]、#[name = "value"]、#[name(key = "value")]。#[derive]、#[proc_macro_attribute])如何被触发。#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")] 为代表的真实属性。
## 34.1 什么是属性:先回答“是宏吗”属性(attribute)不是普通宏调用,而是一种独立的语法。它给编译器、宏、外部工具提供关于代码的“元信息”或“指示”。区分三者:
| 语法 | 名称 | 特征 | 例子 |
#[...] / #![...] | 属性 | 方括号 + 属性名,不写调用括号 | #[derive(Debug)]、#![no_std] |
name!(...) | 声明式宏调用 | 名字加 ! 加圆括号 | println!、vec! |
#[name] 由过程宏处理 | 属性宏(一种过程宏) | 属性形式、在编译期展开代码 | #[derive(Serialize)]、#[tokio::main] |
关键结论:#![...] 是属性语法。它可以是——
cfg、cfg_attr、derive、allow、no_std,由 rustc 直接理解;#[tokio::main],由第三方 crate 注册的宏在编译期接管并展开成代码;
所以严格地说,“属性是宏吗”要看它由谁实现:内置属性依赖编译器,属性宏本身是一种过程宏。但语法上一律用方括号,这一点和 !() 宏完全不同。
属性有 #(外层) 与 #!(内层) 两种:
| 写法 | 名称 | 作用对象 | 典型位置 |
#[attr] | 外层属性 | 紧跟在它后面那一个 item | 结构体、函数、枚举上方 |
#![attr] | 内层属性 | 整个作用域(crate / 模块 / 块) | crate 根顶部、模块开头 |
// 外层属性:只作用在下一个结构体上 #[derive(Debug)] struct Point { x: i32, y: i32 } // 内层属性:作用到整个 crate(必须写在 main.rs / lib.rs 顶部) #![allow(dead_code)] fn main() {}
外层属性作用对象是“紧随其后的那一个代码项”,内层属性作用对象是“它所在的整个单元”。#![...] 带叹号,必须出现在对应作用域(crate 根、模块、函数块)的开头、任何 item 之前。
属性名后面可以带参数,共有三种写法:
// 1) 无参数 #[inline] fn f() {} // 2) 单个值(path / key-value),字符串形式 #[doc = "这是文档"] #[allow(unused_imports)] // 3) 元数据列表:key = value,用逗号分隔 #[cfg(target_os = "windows")] #[link(name = "m", kind = "static")]
属性可以写在同一行用逗号分隔,更常见的做法是注释形式多行叠加:
#[derive(Debug, Clone)] #[allow(dead_code)] struct Config { db_url: String }
// 只在 Windows 编译这个函数 #[cfg(target_os = "windows")] fn only_windows() {} // 组合条件:any / all / not #[cfg(any(target_os = "linux", target_os = "macos"))] fn unix_style() {} #[cfg(debug_assertions)] fn debug_build() {}
常见条件片段:test(测试构建)、debug_assertions(debug 构建)、target_os、feature = "xxx"(Cargo feature)。
cfg_attr 是“如果条件成立,就再多加一个属性”:
#[cfg_attr(debug_assertions, allow(dead_code))] struct DebugOnly { field: i32 }
它在 debug 构建时额外贴 #[allow(dead_code)]。最常见的真实用法就是:
// release 构建下给 crate 贴上"Windows GUI 无控制台"属性 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
含义:not(debug_assertions) 为真(即 release 构建)时,注入 windows_subsystem = "windows",让 Windows GUI 程序发布时不弹出黑色控制台;debug 构建则保留控制台方便看日志。
cfg 控制代码是否编译;cfg_attr 控制某个属性是否被注入到所在的 item 上。
#[derive] 让编译器自动实现某些 trait,是写 Rust 最常用的属性:
#[derive(Debug, Clone, PartialEq, Eq)] struct Point { x: i32, y: i32 } #[derive(Default)] struct Config { port: u16, host: String }
Debug:{:#?} 或 {:?} 可打印调试信息。Clone:生成 .clone() 方法。PartialEq / Eq:用 == 比较。Default:生成 Config::default()。
derive 可以理解为一种内置过程宏:编译器照模板生成 trait 实现代码。第三方 crate 也能提供自己的派生:#[derive(Serialize, Deserialize)](serde)、#[derive(Queryable)](diesel)等。
控制编译器警告/lint,是另一个高频用途:
#[allow(unused_variables)] // 允许未使用变量 #[warn(deprecated)] // 提升为警告 #[deny(unsafe_code)] // 使指定 lint 变成硬错误 #[forbid(unsafe_code)] // deny 的更强形式,子模块无法覆盖
常用例子:
fn main() { #[allow(unused_mut)] // 局部作用:只对后面这个 let 生效 let mut x = 5; // x 从未被修改,但不报警告 }
#![...] 放在文件顶部,控制整个 crate / 模块:
| 内层属性 | 作用 |
#![no_std] | 不使用标准库,常用于嵌入式/内核 |
#![crate_name = "my_lib"] | 显式命名 crate(较少用,一般走 Cargo) |
#![allow(dead_code)] | 允许整个 crate 存在未使用代码 |
#![feature(xxx)] | 启用不稳定 nightly feature |
#![cfg_attr(...)] | 条件注入上述任一属性 |
// lib.rs #![no_std] pub fn add(a: i32, b: i32) -> i32 { a + b }
代码生成 / 优化 / 外部接口:
| 属性 | 作用 |
#[inline] / #[inline(always)] | 建议编译器内联函数 |
#[cold] | 标记罕见路径(如错误分支),帮助优化 |
#[must_use] | 返回值被忽略时给出警告 |
#[link(...)] / #[no_mangle] | FFI 外部链接、保留符号名 |
#[repr(C)] | 控制结构体内存布局,用于 FFI |
#[test] | 标记测试函数 |
#[bench] | 标记基准函数(nightly) |
组织 / 文档 / 其它:
| 属性 | 作用 |
#[doc = "..."] | 生成文档注释内容 |
#[deprecated = "msg"] | 标记废弃并提示 |
#[path = "..."] | 覆盖 mod 的默认文件路径 |
#[non_exhaustive] | 禁止外部 crate 完整构造/穷尽匹配该 enum/struct |
除了内置属性,Rust 允许 crate 注册属性宏(attribute macro / derive macro),本质是过程宏:
// tokio 提供的属性宏:把 main 改写成 async 运行时入口 #[tokio::main] async fn main() { ... } // serde 提供派生宏 #[derive(Serialize, Deserialize)] struct User { id: u32, name: String } // clap 提供的属性宏,从结构体生成 CLI #[derive(Parser)] struct Args { #[arg(short, long)] verbose: bool }
这些属性名(tokio::main、Serialize、Parser)不是你写的,而是依赖 crate 在编译期通过 #[proc_macro_attribute] / #[proc_macro_derive] 声明的。调用它们时需要该 crate 已引入 Cargo.toml。
看到 #[xxx] 时,判断它是什么:
cfg、derive、allow、warn、deny、forbid、inline、doc、test、no_std、repr、link、cfg_attr、deprecated、path、must_use、non_exhaustive、no_mangle、cold、global_allocator、panic_handler 等)→ 内置。编译器对未知属性默认给出"unused attribute"或"unknown attribute"警告,可通过 `#![allow(unused_attributes)]` 抑制。
## 34.11 常见误区
#[derive(Debug)] 里没有 !,也不要写成 derive!(Debug)——那是函数宏语法,语义完全不同。#![allow(...)] 必须写在作用域最开始;放在 item 中间会报错。cfg 与 cfg_attr:cfg 管代码存留,cfg_attr 管属性注入,不要混用。#[cfg] 是运行时判断:它只在编译期过滤,不会产生运行时分支。| 概念 | 要点 |
| 属性本质 | 元信息/指示,#[...] 外层、#![...] 内层 |
| 三种参数 | #[name]、#[name = "v"]、#[name(key="v")] |
| 条件编译 | cfg 控制代码,cfg_attr 控制属性注入 |
| 派生 | #[derive(Trait)] 自动生成 trait 实现 |
| 警告控制 | allow / warn / deny / forbid |
| crate 级 | #![no_std]、#![allow(...)]、#![feature(...)] |
| 外部实现 | #[tokio::main]、#[derive(Serialize)] 等由过程宏提供 |
| 常见例子 | #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")] |
#[derive(Clone)] 和 #[tokio::main] 在“由谁处理”上有什么本质区别?debug_assertions 下编译;再用 cfg_attr 让它在 release 下自动附上 #[allow(dead_code)]。cfg 与 cfg_attr 分别控制什么?举一个“按平台注入属性”的真实场景。#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")] 不写成 #![windows_subsystem = "windows"]?debug 构建下会有什么影响?