match 穷尽性检查 ​

什么是穷尽性检查 ​

穷尽性检查(Exhaustiveness Checking)是 Rust 编译器对 match 表达式的一项强制要求:match 的所有分支必须覆盖被匹配值的每一种可能情况。如果有遗漏,编译器会直接报错,不允许通过编译。

这是 Rust 安全性的重要组成部分——它防止你忘记处理某些情况,避免了运行时出现意外行为。

rust
enum TrafficLight {
    Red,
    Yellow,
    Green,
}

fn action(light: TrafficLight) -> &'static str {
    match light {
        TrafficLight::Red => "停",
        TrafficLight::Yellow => "注意",
        TrafficLight::Green => "行",
        // 如果删掉任何一个分支,编译器会报错:
        // error: non-exhaustive patterns: `TrafficLight::Green` not covered
    }
}

fn main() {
    println!("{}", action(TrafficLight::Red));
    println!("{}", action(TrafficLight::Yellow));
    println!("{}", action(TrafficLight::Green));
}

穷尽性检查的工作方式 ​

编译器会分析被匹配值的类型,列出所有可能的值或变体,然后检查 match 的分支是否覆盖了全部。

rust
fn main() {
    // bool 类型只有两个值
    let flag = true;
    match flag {
        true => println!("真"),
        false => println!("假"),
        // 穷尽了,不需要 _
    }

    // Option<T> 有两个变体
    let maybe: Option<i32> = Some(42);
    match maybe {
        Some(v) => println!("有值:{}", v),
        None => println!("无值"),
        // 穷尽了
    }

    // Result<T, E> 有两个变体
    let result: Result<i32, String> = Ok(100);
    match result {
        Ok(v) => println!("成功:{}", v),
        Err(e) => println!("失败:{}", e),
        // 穷尽了
    }

    // 整数类型值太多,通常需要 _ 兜底
    let num: i32 = 5;
    match num {
        1 => println!("一"),
        2 => println!("二"),
        3 => println!("三"),
        _ => println!("其他"),  // 覆盖剩余的所有 i32 值
    }
}

通配符 _ 和变量绑定 ​

当你无法(或不需要)列出所有具体值时,用 _ 或变量名来匹配剩余情况。

rust
fn main() {
    let code: u32 = 404;

    // _ 不绑定值,只是"忽略"
    match code {
        200 => println!("OK"),
        404 => println!("Not Found"),
        500 => println!("Server Error"),
        _ => println!("状态码:{}", code),  // _ 不能在这里引用
    }

    // 用变量名绑定剩余值
    match code {
        200 => println!("OK"),
        404 => println!("Not Found"),
        500 => println!("Server Error"),
        other => println!("状态码:{}", other),  // other 绑定了匹配的值
    }
}

枚举新增变体时的安全保障 ​

穷尽性检查最大的价值体现在枚举新增变体时——编译器会找出所有没有处理新变体的 match,强迫你逐个更新。

rust
// 假设一开始枚举只有三个变体
enum Shape {
    Circle(f64),
    Rectangle(f64, f64),
    Triangle(f64, f64, f64),
    // 后来新增了一个变体:
    // Polygon(Vec<(f64, f64)>),
}

fn area(shape: &Shape) -> f64 {
    match shape {
        Shape::Circle(r) => std::f64::consts::PI * r * r,
        Shape::Rectangle(w, h) => w * h,
        Shape::Triangle(a, b, c) => {
            // 海伦公式
            let s = (a + b + c) / 2.0;
            (s * (s - a) * (s - b) * (s - c)).sqrt()
        }
        // 如果新增了 Polygon 变体但这里没处理,
        // 编译器会报错:non-exhaustive patterns: `Polygon(_)` not covered
        // 这就迫使你更新所有相关代码
    }
}

fn main() {
    let shapes = vec![
        Shape::Circle(5.0),
        Shape::Rectangle(4.0, 6.0),
        Shape::Triangle(3.0, 4.0, 5.0),
    ];

    for shape in &shapes {
        println!("面积:{:.2}", area(shape));
    }
}

不要滥用 _ 通配符 ​

用 _ 虽然能让编译通过,但会失去穷尽性检查的保护。

rust
enum Permission {
    Read,
    Write,
    Execute,
    Admin,
}

fn check_permission(perm: &Permission) -> bool {
    // 不推荐:用 _ 会在新增变体时静默"放行"
    // match perm {
    //     Permission::Admin => true,
    //     _ => false,  // 如果后来新增了 SuperAdmin 变体,这里不会报错,但逻辑可能错误
    // }

    // 推荐:显式列出所有变体
    match perm {
        Permission::Read => false,
        Permission::Write => false,
        Permission::Execute => false,
        Permission::Admin => true,
        // 新增变体时编译器会提醒你在这里加上处理
    }
}

fn main() {
    println!("Admin: {}", check_permission(&Permission::Admin));
    println!("Read: {}", check_permission(&Permission::Read));
}

基本示例 ​

用穷尽性检查确保状态机的完整性:

rust
#[derive(Debug)]
enum OrderStatus {
    Created,
    Paid,
    Shipped,
    Delivered,
    Cancelled,
    Refunded,
}

fn next_action(status: &OrderStatus) -> &'static str {
    // 显式列出所有状态,不用 _
    // 如果将来新增状态(如 Returning),编译器会要求更新这里
    match status {
        OrderStatus::Created => "等待付款",
        OrderStatus::Paid => "准备发货",
        OrderStatus::Shipped => "等待签收",
        OrderStatus::Delivered => "订单完成",
        OrderStatus::Cancelled => "已取消,无需操作",
        OrderStatus::Refunded => "已退款,无需操作",
    }
}

fn can_cancel(status: &OrderStatus) -> bool {
    match status {
        OrderStatus::Created | OrderStatus::Paid => true,
        OrderStatus::Shipped | OrderStatus::Delivered
        | OrderStatus::Cancelled | OrderStatus::Refunded => false,
    }
}

fn main() {
    let statuses = vec![
        OrderStatus::Created,
        OrderStatus::Paid,
        OrderStatus::Shipped,
        OrderStatus::Delivered,
        OrderStatus::Cancelled,
    ];

    for status in &statuses {
        println!("{:?} -> {}(可取消:{})",
            status, next_action(status), can_cancel(status));
    }
}

常见问题 ​

问题一:为什么整数类型需要 _ 而枚举不需要?

因为整数的值域太大(比如 i32 有约 43 亿个可能的值),不可能逐个列出。枚举的变体数量是有限的,编译器可以检查是否全部覆盖。

问题二:穷尽性检查只适用于 match 吗?

match 是强制穷尽的。if let 不强制穷尽(它只处理一种模式)。let-else 也不需要穷尽(else 分支处理所有不匹配的情况)。

问题三:非穷尽枚举(#[non_exhaustive])是什么?

标记了 #[non_exhaustive] 的枚举表示将来可能新增变体。在外部 crate 中匹配这种枚举时,即使列出了所有当前变体,也必须加 _ 分支。这是库作者预留的扩展空间。

rust
// 如果某个库定义了:
// #[non_exhaustive]
// pub enum Error { NotFound, Timeout, ... }
// 那么在你的代码中:
// match err {
//     Error::NotFound => ...,
//     Error::Timeout => ...,
//     _ => ...,  // 必须有 _,即使当前变体都列出了
// }

问题四:什么时候用 _,什么时候显式列出?

场景建议理由
自己定义的枚举显式列出所有变体新增变体时编译器会提醒
外部库的枚举显式列出 + _ 兜底库升级可能新增变体
整数/字符串等必须用 _值域太大,无法穷尽
只关心几个值用 _ 处理剩余简洁

适用场景 ​

  • 枚举状态机:确保每种状态都被处理
  • 错误处理:确保每种错误类型都有对应的处理逻辑
  • 协议消息处理:确保每种消息类型都被处理
  • 重构安全:新增枚举变体时自动发现需要更新的代码

注意事项 ​

  • match 的穷尽性检查是编译器强制的,不能绕过
  • 用 _ 会失去对新增变体的编译期提醒,谨慎使用
  • 对自己定义的枚举,尽量显式列出所有变体而不是用 _
  • #[non_exhaustive] 枚举在外部使用时必须有 _ 分支
  • bool 类型只有 true 和 false,列出这两个就穷尽了
  • 穷尽性检查是 Rust 相比很多其他语言的独特优势,善用它

总结 ​

穷尽性检查是 Rust match 表达式的核心安全特性——编译器强制要求分支覆盖被匹配值的所有可能情况。对于枚举类型,编译器能精确检查每个变体是否被处理;对于整数等值域巨大的类型,需要用 _ 通配符覆盖剩余情况。穷尽性检查最大的价值在于重构安全:当枚举新增变体时,编译器会找出所有未更新的 match,避免遗漏。对于自己定义的枚举,应该优先显式列出所有变体而不是依赖 _,这样才能充分利用这项编译期保障。