cfg_attr
核心概念
#[cfg_attr(condition, attribute)] 是条件属性语法,它的含义是:当 condition 满足时,将 attribute 应用到被标注的项上;条件不满足时,整个 cfg_attr 被忽略。这让属性的应用也可以根据平台、feature 等条件来决定。
与 #[cfg] 不同,cfg_attr 不会决定项是否存在,而是决定某个属性是否生效。最常见的用途是条件性地应用 derive、serde 属性、lint 控制等。
// 只有启用 serde feature 时才 derive Serialize/Deserialize
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[derive(Debug, Clone)]
struct Config {
name: String,
value: i32,
}
// 在 Windows 上使用不同的 repr
#[cfg_attr(windows, repr(C))]
#[cfg_attr(not(windows), repr(transparent))]
struct Handle {
inner: usize,
}
fn main() {
let config = Config {
name: "test".to_string(),
value: 42,
};
println!("{:?}", config);
}语法格式
// 基本语法
// #[cfg_attr(条件, 属性)]
// 条件满足时应用单个属性
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
struct A;
// 条件满足时应用多个属性(逗号分隔)
#[cfg_attr(feature = "serde",
derive(serde::Serialize, serde::Deserialize),
serde(rename_all = "camelCase")
)]
struct B {
first_name: String,
}
// 嵌套 cfg_attr
#[cfg_attr(feature = "serde",
cfg_attr(feature = "json", derive(serde::Serialize))
)]
struct C;
// 多个独立的 cfg_attr
#[cfg_attr(windows, allow(unused))]
#[cfg_attr(unix, warn(unused))]
fn platform_func() {}
fn main() {}cfg_attr vs cfg
| 特性 | #[cfg(...)] | #[cfg_attr(..., ...)] |
|---|---|---|
| 作用 | 决定项是否编译 | 决定属性是否应用 |
| 条件不满足时 | 项被完全移除 | 属性被移除,项保留 |
| 用途 | 平台代码分支 | 条件性的 derive、lint 等 |
// cfg:条件不满足时整个函数不存在
#[cfg(windows)]
fn windows_only() {}
// 在 Linux 上这个函数不存在
// cfg_attr:条件不满足时属性不生效,但函数仍然存在
#[cfg_attr(windows, inline(always))]
fn maybe_inlined() {
println!("这个函数在所有平台都存在");
println!("但只在 Windows 上强制内联");
}
fn main() {
maybe_inlined();
}常见用法
// === 1. 条件 derive ===
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct User {
pub name: String,
pub age: u32,
}
// === 2. 条件 serde 属性 ===
#[derive(Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct ApiResponse {
#[cfg_attr(feature = "serde", serde(rename = "statusCode"))]
pub status_code: u32,
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub message: Option<String>,
}
// === 3. 条件 repr ===
#[cfg_attr(feature = "ffi", repr(C))]
pub struct FfiStruct {
pub x: f64,
pub y: f64,
}
// === 4. 条件 lint ===
#[cfg_attr(test, allow(dead_code))]
fn helper_function() -> i32 {
42
}
// === 5. 条件 doc ===
#[cfg_attr(docsrs, doc(cfg(feature = "json")))]
#[cfg(feature = "json")]
pub fn parse_json(s: &str) -> Result<(), String> {
Ok(())
}
fn main() {
let user = User {
name: "Alice".to_string(),
age: 30,
};
println!("{:?}", user);
println!("helper: {}", helper_function());
}基本示例
// 综合示例:一个跨平台、多 feature 的结构体
#[derive(Debug, Clone, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct AppConfig {
pub name: String,
#[cfg_attr(feature = "serde", serde(default = "default_port"))]
pub port: u16,
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub log_file: Option<String>,
// 只在 debug 构建中包含此字段
#[cfg(debug_assertions)]
pub debug_mode: bool,
}
#[cfg(feature = "serde")]
fn default_port() -> u16 {
8080
}
impl Default for AppConfig {
fn default() -> Self {
AppConfig {
name: "my-app".to_string(),
port: 8080,
log_file: None,
#[cfg(debug_assertions)]
debug_mode: true,
}
}
}
// 条件性的 Display 实现
#[cfg_attr(not(debug_assertions), allow(unused_variables))]
fn format_config(config: &AppConfig) -> String {
let mut s = format!("{}:{}", config.name, config.port);
#[cfg(debug_assertions)]
{
s.push_str(&format!(" [debug={}]", config.debug_mode));
}
if let Some(ref log) = config.log_file {
s.push_str(&format!(" log={}", log));
}
s
}
fn main() {
let config = AppConfig::default();
println!("配置: {}", format_config(&config));
println!("详细: {:?}", config);
}常见问题
问题一:cfg_attr 中的条件可以用 all/any/not 吗?
可以。条件部分和 #[cfg] 完全相同,支持 all()、any()、not() 以及所有 cfg 谓词。
问题二:cfg_attr 可以嵌套吗?
可以。#[cfg_attr(a, cfg_attr(b, attr))] 表示 a 和 b 都满足时应用 attr。但嵌套过深会影响可读性。
问题三:cfg_attr 和条件编译的 derive 怎么配合?
最常见的模式是 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))],这样只有启用 serde feature 时才会生成序列化代码,不影响不使用 serde 的用户。
问题四:docs.rs 上的 feature 标记怎么实现?
用 #[cfg_attr(docsrs, doc(cfg(feature = "name")))] 配合 docs.rs 的构建配置,在文档中标注哪些功能需要启用特定 feature。
适用场景
- 条件 derive:根据 feature 决定是否实现 Serialize 等
- 条件 serde 属性:重命名、跳过等配置
- 条件 repr:FFI 场景下的内存布局控制
- 条件 lint:在特定平台或配置下调整警告级别
- 文档标注:在 docs.rs 上显示 feature 要求
注意事项
- cfg_attr 不影响项是否存在,只影响属性是否应用
- 条件部分支持所有 cfg 谓词和逻辑组合
- 一个 cfg_attr 可以同时应用多个属性(逗号分隔)
- cfg_attr 可以嵌套但不建议过深
- 与
#[cfg]配合使用时注意两者的区别 - docsrs 条件用于 docs.rs 文档构建
总结
#[cfg_attr(condition, attribute)] 在条件满足时应用指定的属性,条件不满足时属性被忽略但项本身保留。与 #[cfg] 的区别在于:cfg 决定项是否存在,cfg_attr 决定属性是否生效。最常见的用法是条件性的 derive(如 #[cfg_attr(feature = "serde", derive(Serialize))])和条件性的 serde 属性。支持在一个 cfg_attr 中应用多个属性,也支持嵌套。条件部分与 #[cfg] 完全一致,支持所有 cfg 谓词和逻辑组合。