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/工具读取的自定义属性。

所以严格地说,“属性是宏吗”要看它由谁实现:内置属性依赖编译器,属性宏本身是一种过程宏。但语法上一律用方括号,这一点和 !() 宏完全不同。

属性有 #(外层) 与 #!(内层) 两种:

写法 名称 作用对象 典型位置
#[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 之前。

属性名后面可以带参数,共有三种写法:

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 }
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 是“如果条件成立,就再多加一个属性”:

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 控制代码是否编译;cfg_attr 控制某个属性是否被注入到所在的 item 上。

#[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)等。

控制编译器警告/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 从未被修改,但不报警告
}

#![...] 放在文件顶部,控制整个 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 }

代码生成 / 优化 / 外部接口:

属性 作用
#[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),本质是过程宏:

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。

看到 #[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")]
  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 构建下会有什么影响?

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • rust/属性.txt
  • 最后更改: 2026/08/17 09:29
  • 由 张叶安