34. Rust 属性(Attributes)全面指南
学习目标
- 理解属性(attribute)是什么,它与宏、声明式宏的区别。
- 掌握内层属性
#![...]与外层属性#[...]的语法、作用范围与使用位置。 - 掌握属性参数的三种传参形式:
#[name]、#[name = "value"]、#[name(key = "value")]。 - 分门别类掌握 Rust 内置属性:条件编译、派生、警告/错误控制、代码生成、crate 级与模块级属性。
- 理解自定义过程宏属性(
#[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 注册的宏在编译期接管并展开成代码; - 其它 crate 提供给 IDE/工具读取的自定义属性。
所以严格地说,“属性是宏吗”要看它由谁实现:内置属性依赖编译器,属性宏本身是一种过程宏。但语法上一律用方括号,这一点和 !() 宏完全不同。
34.2 内层属性与外层属性
属性有 #(外层) 与 #!(内层) 两种:
| 写法 | 名称 | 作用对象 | 典型位置 |
#[attr] | 外层属性 | 紧跟在它后面那一个 item | 结构体、函数、枚举上方 |
#![attr] | 内层属性 | 整个作用域(crate / 模块 / 块) | crate 根顶部、模块开头 |
- snippet.rust
// 外层属性:只作用在下一个结构体上 #[derive(Debug)] struct Point { x: i32, y: i32 } // 内层属性:作用到整个 crate(必须写在 main.rs / lib.rs 顶部) #![allow(dead_code)] fn main() {}
外层属性作用对象是“紧随其后的那一个代码项”,内层属性作用对象是“它所在的整个单元”。#![...] 带叹号,必须出现在对应作用域(crate 根、模块、函数块)的开头、任何 item 之前。
34.3 属性的三种参数形式
属性名后面可以带参数,共有三种写法:
- snippet.rust
// 1) 无参数 #[inline] fn f() {} // 2) 单个值(path / key-value),字符串形式 #[doc = "这是文档"] #[allow(unused_imports)] // 3) 元数据列表:key = value,用逗号分隔 #[cfg(target_os = "windows")] #[link(name = "m", kind = "static")]
属性可以写在同一行用逗号分隔,更常见的做法是注释形式多行叠加:
- snippet.rust
#[derive(Debug, Clone)] #[allow(dead_code)] struct Config { db_url: String }
34.4 条件编译属性:`cfg` 与 `cfg_attr`
`cfg`:按条件决定代码去留
- snippet.rust
// 只在 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 是“如果条件成立,就再多加一个属性”:
- snippet.rust
#[cfg_attr(debug_assertions, allow(dead_code))] struct DebugOnly { field: i32 }
它在 debug 构建时额外贴 #[allow(dead_code)]。最常见的真实用法就是:
- snippet.rust
// release 构建下给 crate 贴上"Windows GUI 无控制台"属性 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
含义:not(debug_assertions) 为真(即 release 构建)时,注入 windows_subsystem = "windows",让 Windows GUI 程序发布时不弹出黑色控制台;debug 构建则保留控制台方便看日志。
`cfg` vs `cfg_attr` 一句话
cfg 控制代码是否编译;cfg_attr 控制某个属性是否被注入到所在的 item 上。
34.5 `derive`:派生 trait 的生成
#[derive] 让编译器自动实现某些 trait,是写 Rust 最常用的属性:
- snippet.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)等。
34.6 警告与错误控制
控制编译器警告/lint,是另一个高频用途:
- snippet.rust
#[allow(unused_variables)] // 允许未使用变量 #[warn(deprecated)] // 提升为警告 #[deny(unsafe_code)] // 使指定 lint 变成硬错误 #[forbid(unsafe_code)] // deny 的更强形式,子模块无法覆盖
常用例子:
- snippet.rust
fn main() { #[allow(unused_mut)] // 局部作用:只对后面这个 let 生效 let mut x = 5; // x 从未被修改,但不报警告 }
34.7 crate 级与模块级内层属性
#![...] 放在文件顶部,控制整个 crate / 模块:
| 内层属性 | 作用 |
#![no_std] | 不使用标准库,常用于嵌入式/内核 |
#![crate_name = "my_lib"] | 显式命名 crate(较少用,一般走 Cargo) |
#![allow(dead_code)] | 允许整个 crate 存在未使用代码 |
#![feature(xxx)] | 启用不稳定 nightly feature |
#![cfg_attr(...)] | 条件注入上述任一属性 |
- snippet.rust
// lib.rs #![no_std] pub fn add(a: i32, b: i32) -> i32 { a + b }
34.8 其它常用属性一览
代码生成 / 优化 / 外部接口:
| 属性 | 作用 |
#[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 |
34.9 属性宏:第三方提供的属性
除了内置属性,Rust 允许 crate 注册属性宏(attribute macro / derive macro),本质是过程宏:
- snippet.rust
// 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。
34.10 如何区分"内置"与"宏属性"
看到 #[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等)→ 内置。 - 否则是否有 crate 定义了同名过程宏 → 属性宏。
- 否则 → 可能是给 IDE / 工具读的自定义元信息,编译器可能忽略或报未知属性警告。
编译器对未知属性默认给出"unused attribute"或"unknown attribute"警告,可通过 `#![allow(unused_attributes)]` 抑制。
## 34.11 常见误区
- 把属性当声明式宏写:
#[derive(Debug)]里没有!,也不要写成derive!(Debug)——那是函数宏语法,语义完全不同。 - 内层属性放错位置:
#![allow(...)]必须写在作用域最开始;放在 item 中间会报错。 - 混淆
cfg与cfg_attr:cfg管代码存留,cfg_attr管属性注入,不要混用。 - 以为
#[cfg]是运行时判断:它只在编译期过滤,不会产生运行时分支。 - 不确定某属性由谁实现:先查是否内置,再查依赖是否提供对应过程宏,别瞎猜。 ## 34.12 小结
| 概念 | 要点 |
| 属性本质 | 元信息/指示,#[...] 外层、#![...] 内层 |
| 三种参数 | #[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")] |
34.13 思考题
#[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 构建下会有什么影响?