panic! 宏
核心概念
panic! 是 Rust 中用来触发不可恢复错误的宏。当程序遇到无法继续执行的致命情况时,调用 panic! 会立即终止当前线程的执行,打印错误信息,并开始栈展开(unwinding)——逐层调用已创建值的析构函数来释放资源,然后退出。panic! 用于表示程序中的 bug 或违反了不变条件(invariant),而不是用于处理预期的错误情况。
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!
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(运行时检查失败)
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!("所有安全操作完成");
}断言宏
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 时 panic | debug 模式相等检查 |
panic! 的输出信息
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
// 应该 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!
// 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 在参数验证和防御性编程中的用法:
#[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 来处理。