模式匹配

是什么，为什么存在

Rust 的模式描述一个值必须具有的结构，并可为结构中的数据创建绑定。模式能匹配枚举变体、结构体字段、元组、切片、字面值和范围；它不是只比较一个标量的 switch 标签。

match 把一个待匹配值与若干分支从上到下比较，只执行第一个成功分支。编译器要求所有可能值都有去处，并警告永远到不了的分支，因此给枚举添加变体时，显式列举变体的调用点会立刻暴露遗漏。

模式还把检查和取值合成一次操作。Some(order) 同时证明 Option 不是 None，并把内部值绑定为 order；不需要先查询状态，再执行可能失效的取值。

你会在 match 分支、let、函数参数、for、if let、while let、let-else 和 matches! 中遇到模式。它们使用同一套模式语言，但允许失败的程度不同，所以不能只按代码长短互换。宏生成模式、复杂嵌套模式与 API 演进策略等内容属于 rust/pattern-matching-advanced，这里不重复展开。

工作原理

分支选择与穷尽性

match subject { pattern => expression, ... } 先计算一次 subject，再按源码顺序尝试分支。选中的分支产生整个 match 表达式的值，因此所有可到达分支必须得到兼容的结果类型。

穷尽性检查根据类型与模式覆盖范围进行，不会执行代码来猜测条件。布尔值只有两个可能值，普通枚举有已声明的变体，而整数通常需要范围或兜底模式；匹配守卫中的任意布尔表达式不算静态覆盖。

顺序会改变行为。较宽的范围、变量绑定或 _ 放在前面会遮住后面的精确模式，编译器通常以 unreachable_patterns 警告指出这种分支。

解构与绑定

模式既能测试，也能绑定。Request::Read { id } 先要求值是 Read 变体，再把字段绑定为局部变量 id；Request::Read { id: 0 } 则测试字段，但不创建同名变量。

_ 匹配并忽略一个值，.. 忽略结构或序列中剩余的部分。name @ subpattern 在要求 subpattern 成功的同时，把匹配到的完整部分绑定为 name，适合既要验证范围又要继续使用原值的场景。

多个模式可用 | 连接，但每个候选必须创建相同名字、相同类型和相同绑定方式。1 | 2 | 3 不创建变量；小写裸标识符通常创建新绑定，而不是引用外层同名变量。

可反驳性决定语法位置

能匹配其类型每个可能值的模式是不可反驳模式。let (x, y) = pair 一定成功，所以普通 let、函数参数和 for 绑定可以直接使用它。

可能失败的是 可反驳模式 ，例如 Some(value)、1..=9 或固定长度的切片模式。它必须出现在有失败路径的位置，如 match 分支、if let、while let 或 let-else；let-else 的 else 必须通过 return、break、continue 或发散表达式离开当前路径。

绑定方式与所有权

模式绑定也遵守 Rust 的移动、复制与借用规则。按值匹配拥有型值时，非 Copy 字段默认会被移动，Copy 字段则复制；只移出部分字段会产生 部分移动 ，剩余字段可能还能分别使用，但原结构不能再作为完整值使用。

匹配借用值时， 匹配人体工程学 会在常见结构模式中自动解引用，并让绑定成为引用。match &job { Job { owner, .. } => ... } 中的 owner 因此是借用，而不是从 job 中移出 String。

所有权选择应从匹配对象开始读：match value 允许取得其内容，match &value 只读借用，match &mut value 允许可变借用。ref 和 ref mut 仍可在模式中显式借用字段，但在新代码里，借用整个匹配对象通常更容易审查。

守卫与失败路径

匹配守卫 是分支模式后的 if condition。只有模式先成功，守卫才会求值；守卫为 false 时，匹配继续尝试后面的分支。

守卫能引用该模式创建的绑定，也能读取外部变量。它不把自身条件加入穷尽性证明，所以 Some(x) if x > 0 后面仍要处理其他 Some 值以及 None。

在 A | B if condition 中，守卫作用于整个 A | B，不是只作用于 B。如果候选需要不同条件，应拆成两个分支，让顺序与条件边界都明确。

示例

下面四个例子依次展示穷尽分支、切片解析、借用与移动，以及循环式匹配。所有输出都来自本地 rustc 编译后实际运行的程序。

用枚举封住状态空间

路由函数显式处理每个 Request 变体，并把 match 直接作为返回值。Write 的守卫只处理超限情况，后一个 Write 分支仍负责其余大小。

如果新增 Request::Delete，此函数会因匹配不穷尽而停止编译。若用 _ 取代最后两个显式变体分支，这个提醒便会消失，这正是通配分支有时会削弱演进安全性的原因。

id: 0 是字段子模式，不会绑定 id。下一个分支用 .. 表示该变体的其余字段对当前决定无关，也不会承诺以后新增字段时读取它们。

用切片模式解析命令

split_first() 先把空输入从主路径排除，let-else 让后续代码直接使用 verb 与 args。match 再根据动词和参数切片的长度同时检查命令形状。

#![allow(dead_code)]

#[derive(Debug)]
enum Command<'a> {
    Show { id: u32 },
    Tag { id: u32, label: &'a str },
}

fn parse_command<'a>(parts: &[&'a str]) -> Result<Command<'a>, String> {
    let Some((verb, args)) = parts.split_first() else {
        return Err(String::from("empty command"));
    };

    match (*verb, args) {
        ("show", [id]) => id
            .parse::<u32>()
            .map(|id| Command::Show { id })
            .map_err(|_| String::from("invalid id")),
        ("tag", [id, label @ ("urgent" | "normal")]) => id
            .parse::<u32>()
            .map(|id| Command::Tag { id, label })
            .map_err(|_| String::from("invalid id")),
        _ => Err(String::from("unknown command")),
    }
}

fn main() {
    for parts in [
        &[][..],
        &["show", "17"][..],
        &["tag", "17", "urgent"][..],
        &["tag", "17", "later"][..],
    ] {
        println!("{:?}", parse_command(parts));
    }
}

Err("empty command")
Ok(Show { id: 17 })
Ok(Tag { id: 17, label: "urgent" })
Err("unknown command")

[id] 只匹配恰好一个参数，[id, label] 只匹配恰好两个参数，因此额外参数不会被静默忽略。label @ ("urgent" | "normal") 同时限制允许值并保留命中的标签。

兜底分支在这里合理，因为输入字符串的状态空间开放，函数的契约就是把未支持的形状归为一种错误。它与封闭的内部枚举不同；是否使用 _ 取决于类型边界与错误策略。

先借用检查，再按值取出

inspect() 匹配 &Job，其中的字段绑定都是借用。主函数随后仍拥有 job，可以把它交给 take_owner()，在那里按值解构并移动 String 字段。

struct Job {
    owner: String,
    retries: u8,
}

fn inspect(job: &Job) {
    match job {
        Job {
            owner,
            retries: attempts @ 1..=3,
        } => println!("retry {attempts} for {owner}"),
        Job { owner, retries: 0 } => println!("first attempt for {owner}"),
        Job { owner, retries } => println!("retry {retries} for {owner}"),
    }
}

fn take_owner(job: Job) -> String {
    let Job { owner, .. } = job;
    owner
}

fn main() {
    let job = Job {
        owner: String::from("Mina"),
        retries: 2,
    };

    inspect(&job);
    println!("owner: {}", take_owner(job));
}

retry 2 for Mina
owner: Mina

attempts @ 1..=3 既测试闭区间，也保留实际重试次数。因为匹配对象是共享引用，owner 不会移走字符串；inspect() 返回后，该借用结束。

take_owner() 消费整个 Job，所以移动 owner 符合函数契约。若调用方之后仍要使用 job，正确做法通常是让函数接收 &Job 或 &str，而不是为了让旧签名编译就克隆整个值。

在循环中只处理连续成功值

while let 很适合消费返回 Option 或 Result 的状态型操作。这个例子逐个弹出字符串，let-else 跳过解析失败项，再用范围和守卫分类有效数字。

fn main() {
    let mut pending = vec!["101", "bad", "42", "7"];

    while let Some(text) = pending.pop() {
        let Ok(value) = text.parse::<i32>() else {
            println!("skip: {text}");
            continue;
        };

        match value {
            even @ 0..=100 if even % 2 == 0 => println!("even: {even}"),
            odd @ 0..=100 => println!("odd: {odd}"),
            outside => println!("outside: {outside}"),
        }
    }

    println!("empty: {}", pending.is_empty());
}

odd: 7
even: 42
skip: bad
outside: 101
empty: true

向量采用后进先出顺序，所以输出从 "7" 开始。解析失败通过 continue 满足 let-else 必须离开当前路径的要求，而不合法输入是否应跳过，应由调用方契约决定。

第一个分支的守卫只筛选偶数；第二个范围分支仍需接住区间内的奇数。把第二个分支删掉不会让第一个守卫代表整个 0..=100，编译器也不会把任意 % 条件纳入覆盖证明。

陷阱

延伸阅读

• Rust 1.98 Reference：模式
• Rust 1.98 Reference：match 表达式
• The Rust Programming Language：模式与匹配
• The Rust Programming Language：模式语法
• Rust 1.98 标准库：matches!