panic! 宏 ​

核心概念 ​

panic! 是 Rust 中用来触发不可恢复错误的宏。当程序遇到无法继续执行的致命情况时,调用 panic! 会立即终止当前线程的执行,打印错误信息,并开始栈展开(unwinding)——逐层调用已创建值的析构函数来释放资源,然后退出。panic! 用于表示程序中的 bug 或违反了不变条件(invariant),而不是用于处理预期的错误情况。

rust
fn main() {
    // 最简单的 panic
    // panic!("程序崩溃了!");

    // 带格式化参数的 panic
    let x = 42;
    // panic!("无效的值: {}", x);

    // 不显式调用 panic!,某些操作也会触发 panic
    let v = vec![1, 2, 3];
    // let item = v[10];  // 越界访问会 panic

    println!("这行正常执行");
}

panic! 的触发方式 ​

显式调用 panic! ​

rust
fn divide(a: f64, b: f64) -> f64 {
    if b == 0.0 {
        panic!("除数不能为零!a={}, b={}", a, b);
    }
    a / b
}

fn process_age(age: i32) {
    if age < 0 {
        panic!("年龄不能为负数: {}", age);
    }
    if age > 200 {
        panic!("年龄不合理: {}", age);
    }
    println!("年龄: {}", age);
}

fn main() {
    println!("10 / 2 = {}", divide(10.0, 2.0));
    process_age(25);

    // 以下调用会 panic
    // divide(10.0, 0.0);
    // process_age(-5);
}

隐式 panic(运行时检查失败) ​

rust
fn main() {
    // 数组/Vec 越界
    let v = vec![1, 2, 3];
    // let x = v[5];  // panic: index out of bounds

    // 整数溢出(debug 模式)
    // let x: u8 = 255 + 1;  // debug 模式 panic

    // unwrap 在 None 上调用
    let opt: Option<i32> = None;
    // opt.unwrap();  // panic: called `Option::unwrap()` on a `None` value

    // unwrap 在 Err 上调用
    let result: Result<i32, &str> = Err("错误");
    // result.unwrap();  // panic: called `Result::unwrap()` on an `Err` value

    // slice 操作越界
    let s = "hello";
    // let sub = &s[0..10];  // panic: byte index 10 is out of bounds

    println!("所有安全操作完成");
}

断言宏 ​

rust
fn main() {
    let x = 5;
    let y = 5;

    // assert!:条件为 false 时 panic
    assert!(x == y);
    assert!(x > 0, "x 必须大于 0,实际值: {}", x);

    // assert_eq!:两个值不相等时 panic
    assert_eq!(x, y);
    assert_eq!(x + 1, 6, "计算结果不正确");

    // assert_ne!:两个值相等时 panic
    assert_ne!(x, 0);
    assert_ne!(x, 10, "x 不应该等于 10");

    // debug_assert!:只在 debug 模式下检查
    debug_assert!(x > 0);
    debug_assert_eq!(x, y);
    debug_assert_ne!(x, 0);

    println!("所有断言通过");
}
断言宏条件用途
assert!(expr)expr 为 false 时 panic通用条件检查
assert_eq!(a, b)a != b 时 panic相等检查,输出两个值
assert_ne!(a, b)a == b 时 panic不等检查
debug_assert!(expr)debug 模式下 expr 为 false 时 panic性能敏感的检查
debug_assert_eq!(a, b)debug 模式下 a != b 时 panicdebug 模式相等检查

panic! 的输出信息 ​

rust
fn third(v: &[i32]) -> i32 {
    if v.len() < 3 {
        panic!("需要至少3个元素,实际只有 {} 个", v.len());
    }
    v[2]
}

fn main() {
    // panic 输出包含:
    // 1. 错误消息
    // 2. 文件名和行号
    // 3. 调用栈(设置 RUST_BACKTRACE=1 时)

    let data = vec![1, 2];
    // third(&data);
    // 输出类似:
    // thread 'main' panicked at '需要至少3个元素,实际只有 2 个', src/main.rs:3:9
    // note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

    println!("正常运行");
}

查看完整调用栈的方式:

# Windows PowerShell
$env:RUST_BACKTRACE=1; cargo run

# 完整调用栈
$env:RUST_BACKTRACE="full"; cargo run

何时应该 panic ​

rust
// 应该 panic 的场景:

// 1. 程序中的 bug(不变条件被违反)
fn get_element(v: &[i32], index: usize) -> i32 {
    // 如果调用者传入越界索引,是调用者的 bug
    v[index]
}

// 2. 初始化失败,无法继续运行
fn init_config() -> String {
    // 配置文件缺失 = 程序无法运行
    std::fs::read_to_string("config.toml")
        .expect("配置文件 config.toml 不存在,程序无法启动")
}

// 3. 不应该到达的代码路径
fn process_command(cmd: &str) {
    match cmd {
        "start" => println!("启动"),
        "stop" => println!("停止"),
        _ => unreachable!("未知命令: {}", cmd),
        // unreachable! 也是一种 panic
    }
}

// 不应该 panic 的场景(应该用 Result):

// 1. 用户输入无效 → 返回错误让调用者处理
fn parse_port(s: &str) -> Result<u16, String> {
    s.parse::<u16>().map_err(|e| format!("端口无效: {}", e))
}

// 2. 文件可能不存在 → 这是正常情况
fn read_optional_config(path: &str) -> Option<String> {
    std::fs::read_to_string(path).ok()
}

// 3. 网络请求可能失败 → 预期中的错误
fn fetch_data(url: &str) -> Result<String, String> {
    // 网络错误是预期的,不应该 panic
    Err(String::from("连接超时"))
}

fn main() {
    // 安全地使用可能失败的操作
    match parse_port("8080") {
        Ok(port) => println!("端口: {}", port),
        Err(e) => println!("错误: {}", e),
    }

    if let Some(config) = read_optional_config("optional.toml") {
        println!("可选配置: {}", config);
    } else {
        println!("使用默认配置");
    }
}
场景使用 panic!使用 Result/Option
程序 bug是否
不变条件被违反是否
初始化失败通常是看情况
用户输入错误否是
文件/网络操作失败否是
预期中的错误否是

todo! 和 unimplemented! ​

rust
// todo!:标记还没实现的功能
fn calculate_tax(income: f64) -> f64 {
    if income < 0.0 {
        panic!("收入不能为负数");
    }
    if income < 5000.0 {
        return 0.0;
    }
    todo!("税率计算尚未实现")
    // 编译通过,但运行到这里会 panic
}

// unimplemented!:标记不打算实现的功能
struct ReadOnlyFile;

impl ReadOnlyFile {
    fn read(&self) -> String {
        String::from("文件内容")
    }

    fn write(&self, _data: &str) {
        unimplemented!("只读文件不支持写入操作")
    }
}

fn main() {
    // todo! 用于开发中
    // let tax = calculate_tax(10000.0);  // panic: not yet implemented

    let file = ReadOnlyFile;
    println!("{}", file.read());
    // file.write("test");  // panic: not implemented
}

基本示例 ​

展示 panic 在参数验证和防御性编程中的用法:

rust
#[derive(Debug)]
struct Matrix {
    rows: usize,
    cols: usize,
    data: Vec<f64>,
}

impl Matrix {
    fn new(rows: usize, cols: usize) -> Self {
        assert!(rows > 0, "矩阵行数必须大于 0");
        assert!(cols > 0, "矩阵列数必须大于 0");
        Matrix {
            rows,
            cols,
            data: vec![0.0; rows * cols],
        }
    }

    fn from_vec(rows: usize, cols: usize, data: Vec<f64>) -> Self {
        assert_eq!(
            data.len(), rows * cols,
            "数据长度 {} 不等于 {}x{} = {}",
            data.len(), rows, cols, rows * cols
        );
        Matrix { rows, cols, data }
    }

    fn get(&self, row: usize, col: usize) -> f64 {
        assert!(row < self.rows, "行索引 {} 越界,总行数 {}", row, self.rows);
        assert!(col < self.cols, "列索引 {} 越界,总列数 {}", col, self.cols);
        self.data[row * self.cols + col]
    }

    fn set(&mut self, row: usize, col: usize, value: f64) {
        assert!(row < self.rows, "行索引 {} 越界", row);
        assert!(col < self.cols, "列索引 {} 越界", col);
        self.data[row * self.cols + col] = value;
    }

    fn add(&self, other: &Matrix) -> Matrix {
        assert_eq!(self.rows, other.rows, "矩阵行数不匹配: {} vs {}", self.rows, other.rows);
        assert_eq!(self.cols, other.cols, "矩阵列数不匹配: {} vs {}", self.cols, other.cols);

        let data: Vec<f64> = self.data.iter()
            .zip(other.data.iter())
            .map(|(a, b)| a + b)
            .collect();
        Matrix::from_vec(self.rows, self.cols, data)
    }

    fn display(&self) {
        println!("矩阵 {}x{}:", self.rows, self.cols);
        for r in 0..self.rows {
            let row: Vec<String> = (0..self.cols)
                .map(|c| format!("{:6.1}", self.get(r, c)))
                .collect();
            println!("  [{}]", row.join(", "));
        }
    }
}

fn main() {
    // 正常创建
    let mut m1 = Matrix::new(2, 3);
    m1.set(0, 0, 1.0);
    m1.set(0, 1, 2.0);
    m1.set(0, 2, 3.0);
    m1.set(1, 0, 4.0);
    m1.set(1, 1, 5.0);
    m1.set(1, 2, 6.0);
    m1.display();

    let m2 = Matrix::from_vec(2, 3, vec![10.0, 20.0, 30.0, 40.0, 50.0, 60.0]);
    m2.display();

    let m3 = m1.add(&m2);
    println!("\nm1 + m2 =");
    m3.display();

    // 以下操作会 panic(取消注释可测试):
    // Matrix::new(0, 3);                           // 行数为 0
    // Matrix::from_vec(2, 2, vec![1.0, 2.0]);      // 数据长度不匹配
    // m1.get(5, 0);                                 // 行索引越界
    // m1.add(&Matrix::new(3, 3));                   // 矩阵尺寸不匹配
}

常见问题 ​

问题一:panic 会泄漏内存吗?

默认不会。栈展开(unwinding)模式下,Rust 会逐层调用析构函数释放资源(关闭文件、释放内存等)。但如果设置了 panic = 'abort' 模式,进程会直接终止,不执行析构函数,由操作系统回收资源。

问题二:panic 只影响当前线程吗?

是的。在多线程程序中,一个线程 panic 不会直接影响其他线程。主线程可以通过 thread::spawn 返回的 JoinHandle 检测子线程是否 panic。如果主线程 panic,整个进程退出。

问题三:panic! 和 std::process::exit 有什么区别?

panic! 触发栈展开,执行析构函数,可以被 catch_unwind 捕获。std::process::exit 立即退出进程,不执行析构函数,不能被捕获。

问题四:什么是 unreachable! 宏?

unreachable!() 用于标记逻辑上不可能到达的代码路径。如果运行时到达了,会 panic 并提示这是一个 bug。编译器可以利用 unreachable! 进行优化。

适用场景 ​

  • 不变条件检查:assert 验证函数前置条件
  • 不可恢复的错误:程序的 bug,不应该发生的情况
  • 开发占位符:todo! 和 unimplemented! 标记未完成的代码
  • 防御性编程:在不可能到达的路径使用 unreachable!

注意事项 ​

  • panic! 用于不可恢复的错误,预期错误应该用 Result
  • panic 默认会栈展开并调用析构函数
  • 设置 RUST_BACKTRACE=1 查看完整调用栈
  • assert!、assert_eq!、assert_ne! 在所有模式下都检查
  • debug_assert! 系列只在 debug 模式下检查
  • todo! 和 unimplemented! 本质也是 panic
  • 一个线程的 panic 不会影响其他线程

总结 ​

panic! 是 Rust 处理不可恢复错误的机制,当程序遇到 bug 或违反不变条件时使用。显式调用 panic! 宏、数组越界、unwrap() 失败、断言失败等都会触发 panic。panic 默认采用栈展开模式,逐层调用析构函数释放资源。断言宏(assert!、assert_eq!、assert_ne!)是防御性编程的重要工具。todo! 和 unimplemented! 用于标记未完成的代码。预期中可能发生的错误(如用户输入、文件操作、网络请求)不应该用 panic,而应该用 Result 或 Option 来处理。