可选模式 $( )? ​

核心概念 ​

可选模式 $( ... )? 是 Rust 1.32 稳定引入的重复操作符,表示"匹配零次或一次"。它是 *(零或多次)和 +(一或多次)的补充,专门用于处理"有或没有"的可选参数场景。在此之前,处理可选参数只能通过定义多条规则来实现。

$( ... )? 内部可以包含任意 token 组合,包括片段说明符、字面量 token 等。匹配到的内容在转写器中用同样的 $( ... )? 展开。? 操作符不能有分隔符(因为最多只匹配一次,不需要分隔符)。

rust
// 可选的返回类型
macro_rules! make_fn {
    // $( -> $ret:ty )? 匹配可选的返回类型
    (fn $name:ident() $(-> $ret:ty)? { $($body:tt)* }) => {
        fn $name() $(-> $ret)? {
            $($body)*
        }
    };
}

// 没有返回类型
make_fn!(fn greet() {
    println!("Hello!");
});

// 有返回类型
make_fn!(fn answer() -> i32 {
    42
});

fn main() {
    greet();
    println!("answer = {}", answer());
}

与多规则方式的对比 ​

rust
// === 旧方式:多条规则处理可选参数 ===
macro_rules! old_style {
    // 无可选参数
    ($name:expr) => {
        println!("名称: {}", $name);
    };
    // 有可选参数
    ($name:expr, $desc:expr) => {
        println!("名称: {}, 描述: {}", $name, $desc);
    };
}

// === 新方式:$( )? 处理可选参数 ===
macro_rules! new_style {
    ($name:expr $(, $desc:expr)?) => {
        print!("名称: {}", $name);
        $(
            print!(", 描述: {}", $desc);
        )?
        println!();
    };
}

fn main() {
    old_style!("Alice");
    old_style!("Bob", "开发者");

    new_style!("Alice");
    new_style!("Bob", "开发者");
}
方式代码量可维护性适用场景
多条规则规则数随可选参数组合增长参数多时难维护不同参数形式的逻辑完全不同
$( )?一条规则简洁可选参数只是"有或没有"的差别

常见用法 ​

rust
// 1. 可选的尾随逗号
macro_rules! list {
    ($($item:expr),* $(,)?) => {
        vec![$($item),*]
    };
}

// 2. 可选的可见性修饰符(vis 自带可选语义,但有时需要额外语法)
macro_rules! define_fn {
    ($(pub)? fn $name:ident() $body:block) => {
        // 这里用字面量 pub 匹配
        // 注意:这不如用 $vis:vis 灵活
    };
}

// 3. 可选的泛型约束
macro_rules! make_wrapper {
    ($name:ident($inner:ty) $(where $bound:tt)*) => {
        struct $name {
            inner: $inner,
        }
    };
}

// 4. 可选的初始值
macro_rules! declare {
    ($name:ident : $ty:ty $(= $init:expr)?) => {
        // 用 Option 来处理有或没有初始值
        let $name: $ty;
        $(
            $name = $init;
        )?
        // 如果没有初始值,变量未初始化,后续赋值前不能使用
    };
}

// 5. 可选的文档注释
macro_rules! documented_const {
    ($(#[doc = $doc:literal])? const $name:ident : $ty:ty = $val:expr) => {
        $(#[doc = $doc])?
        const $name: $ty = $val;
    };
}

documented_const!(
    #[doc = "最大重试次数"]
    const MAX_RETRIES: u32 = 3
);

documented_const!(
    const MIN_SIZE: usize = 1
);

fn main() {
    // 尾随逗号
    let v1 = list![1, 2, 3];     // 无尾随逗号
    let v2 = list![1, 2, 3,];    // 有尾随逗号
    println!("{:?} {:?}", v1, v2);

    // 可选初始值
    declare!(x: i32 = 42);
    println!("x = {}", x);

    println!("MAX_RETRIES = {}", MAX_RETRIES);
    println!("MIN_SIZE = {}", MIN_SIZE);
}

$( )? 与 $( )* 的区别 ​

rust
// ? 最多匹配一次,* 可以匹配多次

// 用 ? 的场景:可选的单个参数
macro_rules! greet {
    ($name:expr $(, $title:expr)?) => {
        $(
            print!("{} ", $title);
        )?
        println!("{}", $name);
    };
}

// 用 * 的场景:可变数量的参数
macro_rules! greet_many {
    ($($name:expr),*) => {
        $(
            println!("你好, {}", $name);
        )*
    };
}

// ? 不能有分隔符
// macro_rules! bad {
//     ($($e:expr),?) => {};  // 编译错误:? 不能有分隔符
// }

// * 可以有分隔符
macro_rules! good {
    ($($e:expr),*) => {};  // 合法
}

fn main() {
    greet!("Alice");
    greet!("Alice", "Dr.");

    greet_many!();
    greet_many!("Alice", "Bob", "Carol");
}
特性?*+
最少次数001
最多次数1无限无限
分隔符不允许允许允许
典型场景可选单参数可变参数列表至少一个参数

基本示例 ​

rust
// 综合实战:用可选模式构建灵活的结构体定义宏

macro_rules! entity {
    (
        $(#[doc = $doc:literal])?
        $vis:vis struct $name:ident {
            $(
                $(#[doc = $fdoc:literal])?
                $fvis:vis $fname:ident : $fty:ty $(= $fdefault:expr)?
            ),*
            $(,)?
        }
    ) => {
        $(#[doc = $doc])?
        #[derive(Debug)]
        $vis struct $name {
            $(
                $(#[doc = $fdoc])?
                $fvis $fname: $fty,
            )*
        }

        impl $name {
            $vis fn new(
                $( $fname: $fty, )*
            ) -> Self {
                Self {
                    $( $fname, )*
                }
            }
        }

        // 如果有默认值,生成 default 构造函数
        impl Default for $name {
            fn default() -> Self {
                Self {
                    $(
                        $fname: entity!(@default $fty $(, $fdefault)?),
                    )*
                }
            }
        }
    };

    // 内部辅助规则:处理可选的默认值
    (@default $ty:ty, $val:expr) => { $val };
    (@default $ty:ty) => { <$ty as Default>::default() };
}

entity! {
    #[doc = "用户配置"]
    pub struct UserConfig {
        #[doc = "用户名"]
        pub name: String = String::from("guest"),
        pub age: u32 = 0,
        pub email: String,
        pub active: bool = true,
    }
}

// 可选模式在错误处理宏中的应用
macro_rules! try_or {
    ($expr:expr $(, $fallback:expr)?) => {{
        match $expr {
            Ok(val) => val,
            Err(_e) => {
                $(return $fallback;)?
                // 如果没有 fallback,继续执行(这行不会到达如果有 fallback)
                #[allow(unreachable_code)]
                {
                    panic!("操作失败");
                }
            }
        }
    }};
}

fn parse_number(s: &str) -> Result<i32, String> {
    s.parse::<i32>().map_err(|e| e.to_string())
}

fn process(input: &str) -> i32 {
    let num = try_or!(parse_number(input), -1);
    num * 2
}

fn main() {
    // 使用默认值
    let default_config = UserConfig::default();
    println!("默认: {:?}", default_config);

    // 使用自定义值
    let custom_config = UserConfig::new(
        "Alice".to_string(),
        30,
        "alice@example.com".to_string(),
        true,
    );
    println!("自定义: {:?}", custom_config);

    // try_or
    println!("parse '42': {}", process("42"));
    println!("parse 'abc': {}", process("abc"));
}

常见问题 ​

问题一:$( )? 是什么时候稳定的?

Rust 1.32.0(2019年1月发布)。在此之前只能用多条规则或 $( )* 配合额外逻辑来模拟可选参数。

问题二:$( )? 内部可以有多个 token 吗?

可以。$( ... )? 内部可以是任意 token 组合,包括多个片段说明符、字面量 token 等。整个组要么全部匹配,要么全部不匹配。

问题三:$( )? 和直接用 $( ) 有什么实际差别?*

语义上更精确——? 明确表示"最多一次",* 表示"任意次"。使用 ? 可以避免意外匹配多次。另外 ? 不允许分隔符,而 * 允许。

问题四:可选模式中的变量如果没匹配到怎么办?

转写器中对应的 $( ... )? 块不会展开,相当于没有这段代码。这不会报错,也不会产生任何输出。

适用场景 ​

  • 尾随逗号:$(,)? 允许列表最后有可选逗号
  • 可选返回类型:$(-> $ret:ty)?
  • 可选属性/文档:$(#[doc = $doc:literal])?
  • 可选默认值:$(= $default:expr)?
  • 可选泛型约束:$(where $bounds:tt)*

注意事项 ​

  • ? 不能有分隔符,与 * 和 + 不同
  • ? 最多匹配一次,不能用于列表
  • 转写器中的 $( ... )? 会在没匹配时被完全省略
  • 对于 vis 片段说明符,它本身就隐含可选语义
  • 如果不同参数组合的处理逻辑差异很大,多条规则比 ? 更清晰

总结 ​

$( )? 是声明宏中的可选模式操作符,匹配零次或一次。它让宏能优雅地处理"有或没有"的参数,替代了之前需要多条规则的写法。? 不能有分隔符,内部可以包含任意 token 组合。最常见的用法是 $(,)? 处理尾随逗号、$(-> $ret:ty)? 处理可选返回类型、$(= $default:expr)? 处理可选默认值。转写器中对应的 $( ... )? 在未匹配时会被完全省略。当不同参数组合需要完全不同的处理逻辑时,多条规则依然比 ? 更合适。