# 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]` | 关键结论:`#![...]` 是**属性语法**。它可以是—— 1. **编译器内置属性**:如 `cfg`、`cfg_attr`、`derive`、`allow`、`no_std`,由 rustc 直接理解; 2. **过程宏(属性宏)**:如 `#[tokio::main]`,由第三方 crate 注册的宏在编译期接管并展开成代码; 3. **其它 crate 提供给 IDE/工具读取的自定义属性**。 所以严格地说,"属性是宏吗"要看它由谁实现:内置属性依赖编译器,属性宏本身是一种过程宏。但**语法上一律用方括号**,这一点和 `!()` 宏完全不同。 ## 34.2 内层属性与外层属性 属性有 **`#`(外层)** 与 **`#!`(内层)** 两种: | 写法 | 名称 | 作用对象 | 典型位置 | | `#[attr]` | 外层属性 | 紧跟在它**后面那一个 item** | 结构体、函数、枚举上方 | | `#![attr]` | 内层属性 | 整个**作用域**(crate / 模块 / 块) | crate 根顶部、模块开头 | ```rust // 外层属性:只作用在下一个结构体上 #[derive(Debug)] struct Point { x: i32, y: i32 } // 内层属性:作用到整个 crate(必须写在 main.rs / lib.rs 顶部) #![allow(dead_code)] fn main() {} ``` 外层属性作用对象是"紧随其后的那一个代码项",内层属性作用对象是"它所在的整个单元"。`#![...]` 带叹号,必须出现在对应作用域(crate 根、模块、函数块)的开头、任何 item 之前。 ## 34.3 属性的三种参数形式 属性名后面可以带参数,共有三种写法: ```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")] ``` 属性可以写在同一行用逗号分隔,更常见的做法是**注释形式多行叠加**: ```rust #[derive(Debug, Clone)] #[allow(dead_code)] struct Config { db_url: String } ``` ## 34.4 条件编译属性:`cfg` 与 `cfg_attr` ### `cfg`:按条件决定代码去留 ```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` 是"如果条件成立,就再多加一个属性": ```rust #[cfg_attr(debug_assertions, allow(dead_code))] struct DebugOnly { field: i32 } ``` 它在 debug 构建时额外贴 `#[allow(dead_code)]`。最常见的真实用法就是: ```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 最常用的属性: ```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,是另一个高频用途: ```rust #[allow(unused_variables)] // 允许未使用变量 #[warn(deprecated)] // 提升为警告 #[deny(unsafe_code)] // 使指定 lint 变成硬错误 #[forbid(unsafe_code)] // deny 的更强形式,子模块无法覆盖 ``` 常用例子: ```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(...)]` | 条件注入上述任一属性 | ```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),本质是过程宏: ```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]` 时,判断它是什么: 1. 名字是否在标准库内置列表(`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` 等)→ 内置。 2. 否则是否有 crate 定义了同名过程宏 → 属性宏。 3. 否则 → 可能是给 IDE / 工具读的自定义元信息,编译器可能忽略或报未知属性警告。 > 编译器对未知属性默认给出"unused attribute"或"unknown attribute"警告,可通过 `#![allow(unused_attributes)]` 抑制。 ## 34.11 常见误区 1. **把属性当声明式宏写**:`#[derive(Debug)]` 里没有 `!`,也不要写成 `derive!(Debug)`——那是函数宏语法,语义完全不同。 2. **内层属性放错位置**:`#![allow(...)]` 必须写在作用域最开始;放在 item 中间会报错。 3. **混淆 `cfg` 与 `cfg_attr`**:`cfg` 管代码存留,`cfg_attr` 管属性注入,不要混用。 4. **以为 `#[cfg]` 是运行时判断**:它只在编译期过滤,不会产生运行时分支。 5. **不确定某属性由谁实现**:先查是否内置,再查依赖是否提供对应过程宏,别瞎猜。 ## 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 思考题 1. `#[derive(Clone)]` 和 `#[tokio::main]` 在"由谁处理"上有什么本质区别? 2. 写一个函数,仅在其 `debug_assertions` 下编译;再用 `cfg_attr` 让它在 release 下自动附上 `#[allow(dead_code)]`。 3. `cfg` 与 `cfg_attr` 分别控制什么?举一个"按平台注入属性"的真实场景。 4. 为什么 `#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]` 不写成 `#![windows_subsystem = "windows"]`?debug 构建下会有什么影响?