cfg_attr ​

核心概念 ​

#[cfg_attr(condition, attribute)] 是条件属性语法,它的含义是:当 condition 满足时,将 attribute 应用到被标注的项上;条件不满足时,整个 cfg_attr 被忽略。这让属性的应用也可以根据平台、feature 等条件来决定。

与 #[cfg] 不同,cfg_attr 不会决定项是否存在,而是决定某个属性是否生效。最常见的用途是条件性地应用 derive、serde 属性、lint 控制等。

rust
// 只有启用 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);
}

语法格式 ​

rust
// 基本语法
// #[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 等
rust
// cfg:条件不满足时整个函数不存在
#[cfg(windows)]
fn windows_only() {}
// 在 Linux 上这个函数不存在

// cfg_attr:条件不满足时属性不生效,但函数仍然存在
#[cfg_attr(windows, inline(always))]
fn maybe_inlined() {
    println!("这个函数在所有平台都存在");
    println!("但只在 Windows 上强制内联");
}

fn main() {
    maybe_inlined();
}

常见用法 ​

rust
// === 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());
}

基本示例 ​

rust
// 综合示例:一个跨平台、多 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 谓词和逻辑组合。