panic hook 自定义 ​

核心概念 ​

Panic Hook 是 Rust 提供的一种机制,允许你自定义 panic 发生时的行为。默认情况下,panic 会打印错误信息和位置到标准错误输出(stderr)。通过 std::panic::set_hook 可以替换这个默认行为,实现自定义的错误日志记录、报警通知、错误报告上传等功能。Hook 在栈展开之前执行,此时 panic 信息是完整的。

rust
use std::panic;

fn main() {
    // 设置自定义 panic hook
    panic::set_hook(Box::new(|panic_info| {
        // panic_info 包含错误消息和位置信息
        eprintln!("=== 自定义 Panic 处理 ===");

        // 获取 panic 消息
        if let Some(msg) = panic_info.payload().downcast_ref::<&str>() {
            eprintln!("消息: {}", msg);
        } else if let Some(msg) = panic_info.payload().downcast_ref::<String>() {
            eprintln!("消息: {}", msg);
        }

        // 获取 panic 位置
        if let Some(location) = panic_info.location() {
            eprintln!("位置: {}:{}:{}", location.file(), location.line(), location.column());
        }

        eprintln!("=========================");
    }));

    // 触发 panic,会调用自定义 hook
    panic!("测试自定义 hook");
}

PanicInfo 结构 ​

set_hook 的闭包接收一个 &PanicInfo 参数,它包含了 panic 的所有相关信息。

rust
use std::panic;

fn main() {
    panic::set_hook(Box::new(|info| {
        // payload():获取 panic 的负载(消息)
        // 可能是 &str 或 String 类型
        let message = if let Some(s) = info.payload().downcast_ref::<&str>() {
            s.to_string()
        } else if let Some(s) = info.payload().downcast_ref::<String>() {
            s.clone()
        } else {
            String::from("(无法获取消息)")
        };

        // location():获取 panic 发生的代码位置
        let location = match info.location() {
            Some(loc) => format!("{}:{}:{}", loc.file(), loc.line(), loc.column()),
            None => String::from("未知位置"),
        };

        eprintln!("[PANIC] {} @ {}", message, location);
    }));

    // 不同方式触发 panic
    let result = panic::catch_unwind(|| {
        panic!("字符串字面量消息");  // payload 是 &str
    });
    println!("捕获1: {:?}", result.is_err());

    let result = panic::catch_unwind(|| {
        panic!("格式化消息: {}", 42);  // payload 是 String
    });
    println!("捕获2: {:?}", result.is_err());

    let result = panic::catch_unwind(|| {
        let v: Vec<i32> = vec![];
        v[0];  // 越界 panic,payload 是 String
    });
    println!("捕获3: {:?}", result.is_err());
}

日志记录 Hook ​

rust
use std::panic;
use std::fs::OpenOptions;
use std::io::Write;

// 将 panic 信息写入日志文件
fn setup_panic_logger(log_path: &'static str) {
    panic::set_hook(Box::new(move |info| {
        let message = if let Some(s) = info.payload().downcast_ref::<&str>() {
            s.to_string()
        } else if let Some(s) = info.payload().downcast_ref::<String>() {
            s.clone()
        } else {
            String::from("未知错误")
        };

        let location = info.location()
            .map(|l| format!("{}:{}", l.file(), l.line()))
            .unwrap_or_else(|| String::from("未知"));

        let log_entry = format!(
            "[PANIC] 消息: {} | 位置: {}\n",
            message, location
        );

        // 输出到 stderr
        eprint!("{}", log_entry);

        // 同时写入日志文件
        if let Ok(mut file) = OpenOptions::new()
            .create(true)
            .append(true)
            .open(log_path)
        {
            let _ = file.write_all(log_entry.as_bytes());
        }
    }));
}

fn main() {
    setup_panic_logger("panic.log");

    // 测试
    let result = panic::catch_unwind(|| {
        panic!("数据库连接失败");
    });

    if result.is_err() {
        println!("panic 已记录到 panic.log");
    }

    // 清理测试文件
    let _ = std::fs::remove_file("panic.log");
}

获取和恢复默认 Hook ​

rust
use std::panic;

fn main() {
    // take_hook:获取当前 hook 并恢复默认
    // 可以用来在自定义 hook 中调用原始 hook

    // 先设置一个自定义 hook
    panic::set_hook(Box::new(|info| {
        eprintln!("[自定义] panic 发生了!");
        // 获取消息
        if let Some(msg) = info.payload().downcast_ref::<&str>() {
            eprintln!("[自定义] 消息: {}", msg);
        }
    }));

    let result = panic::catch_unwind(|| {
        panic!("第一次 panic");
    });
    println!("第一次: {}", result.is_err());

    // take_hook 取出自定义 hook,恢复默认行为
    let old_hook = panic::take_hook();

    let result = panic::catch_unwind(|| {
        panic!("第二次 panic");
    });
    println!("第二次(默认 hook): {}", result.is_err());

    // 可以重新设置回去
    panic::set_hook(old_hook);

    let result = panic::catch_unwind(|| {
        panic!("第三次 panic");
    });
    println!("第三次(恢复自定义 hook): {}", result.is_err());
}

组合多个 Hook ​

rust
use std::panic;

// 在自定义 hook 中链式调用原有 hook
fn add_panic_handler<F>(handler: F)
where
    F: Fn(&panic::PanicInfo<'_>) + Send + Sync + 'static,
{
    // 取出当前 hook
    let previous_hook = panic::take_hook();

    // 设置新 hook:先执行新的处理,再执行原来的
    panic::set_hook(Box::new(move |info| {
        handler(info);        // 执行新添加的处理
        previous_hook(info);  // 执行之前的 hook
    }));
}

fn main() {
    // 添加第一个处理:记录到 "日志"
    add_panic_handler(|info| {
        let msg = info.payload().downcast_ref::<&str>()
            .map(|s| s.to_string())
            .unwrap_or_default();
        eprintln!("[日志层] 记录 panic: {}", msg);
    });

    // 添加第二个处理:统计计数
    add_panic_handler(|_info| {
        eprintln!("[监控层] panic 计数 +1");
    });

    // panic 时两个处理都会执行(加上默认 hook)
    let result = panic::catch_unwind(|| {
        panic!("测试链式 hook");
    });

    println!("已捕获: {}", result.is_err());
}

线程中的 panic hook ​

panic hook 是全局的,所有线程共享同一个 hook。

rust
use std::panic;
use std::thread;
use std::sync::{Arc, Mutex};

fn main() {
    // 用 Arc<Mutex<Vec>> 收集所有线程的 panic 信息
    let panic_log: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
    let log_clone = Arc::clone(&panic_log);

    panic::set_hook(Box::new(move |info| {
        let thread_name = thread::current().name()
            .unwrap_or("未命名")
            .to_string();

        let message = info.payload().downcast_ref::<&str>()
            .map(|s| s.to_string())
            .or_else(|| info.payload().downcast_ref::<String>().cloned())
            .unwrap_or_else(|| String::from("未知"));

        let entry = format!("[线程:{}] {}", thread_name, message);
        eprintln!("{}", entry);

        if let Ok(mut log) = log_clone.lock() {
            log.push(entry);
        }
    }));

    // 多个线程中 panic
    let handles: Vec<_> = (0..3).map(|i| {
        thread::Builder::new()
            .name(format!("worker-{}", i))
            .spawn(move || {
                if i == 1 {
                    panic!("worker-{} 崩溃了", i);
                }
                println!("worker-{} 正常完成", i);
            })
            .unwrap()
    }).collect();

    // 等待所有线程完成
    for handle in handles {
        let _ = handle.join();
    }

    // 查看收集到的 panic 日志
    let log = panic_log.lock().unwrap();
    println!("\n=== Panic 日志 ({} 条) ===", log.len());
    for entry in log.iter() {
        println!("  {}", entry);
    }
}

基本示例 ​

实现一个完整的 panic 报告系统:

rust
use std::panic;
use std::sync::Mutex;

// 全局 panic 记录器
static PANIC_RECORDS: Mutex<Vec<PanicRecord>> = Mutex::new(Vec::new());

#[derive(Debug, Clone)]
struct PanicRecord {
    message: String,
    file: String,
    line: u32,
    thread: String,
}

impl PanicRecord {
    fn from_panic_info(info: &panic::PanicInfo<'_>) -> Self {
        let message = if let Some(s) = info.payload().downcast_ref::<&str>() {
            s.to_string()
        } else if let Some(s) = info.payload().downcast_ref::<String>() {
            s.clone()
        } else {
            String::from("未知错误")
        };

        let (file, line) = match info.location() {
            Some(loc) => (loc.file().to_string(), loc.line()),
            None => (String::from("未知"), 0),
        };

        let thread = std::thread::current().name()
            .unwrap_or("main")
            .to_string();

        PanicRecord { message, file, line, thread }
    }

    fn format(&self) -> String {
        format!("[{}] {} ({}:{})", self.thread, self.message, self.file, self.line)
    }
}

fn setup_panic_reporter() {
    panic::set_hook(Box::new(|info| {
        let record = PanicRecord::from_panic_info(info);
        eprintln!("PANIC: {}", record.format());

        // 记录到全局列表
        if let Ok(mut records) = PANIC_RECORDS.lock() {
            records.push(record);
        }
    }));
}

fn get_panic_report() -> Vec<PanicRecord> {
    PANIC_RECORDS.lock()
        .map(|r| r.clone())
        .unwrap_or_default()
}

// 模拟不同模块的操作
fn database_operation() {
    panic!("数据库连接池耗尽");
}

fn network_operation() {
    panic!("DNS 解析超时");
}

fn computation() {
    let data: Vec<i32> = vec![];
    // 越界访问
    let _ = data[0];
}

fn main() {
    setup_panic_reporter();

    // 模拟多个可能 panic 的操作
    let operations: Vec<(&str, fn())> = vec![
        ("数据库操作", database_operation),
        ("网络操作", network_operation),
        ("数据计算", computation),
    ];

    for (name, op) in &operations {
        println!("\n执行: {}...", name);
        let result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
            op();
        }));

        match result {
            Ok(()) => println!("  {} 成功", name),
            Err(_) => println!("  {} 失败,已记录", name),
        }
    }

    // 输出报告
    let report = get_panic_report();
    println!("\n====== Panic 报告 ======");
    println!("总计: {} 次 panic", report.len());
    for (i, record) in report.iter().enumerate() {
        println!("  {}. {}", i + 1, record.format());
    }
}

常见问题 ​

问题一:panic hook 是线程安全的吗?

是的。set_hook 要求闭包实现 Send + Sync + 'static,保证 hook 可以在多线程环境中安全使用。如果 hook 内部需要访问共享状态,需要用 Mutex 或 Atomic 等同步原语。

问题二:panic hook 在 abort 模式下还会执行吗?

会。即使设置了 panic = "abort",panic hook 仍然会在进程终止前执行。但 catch_unwind 在 abort 模式下不起作用。

问题三:set_hook 可以调用多次吗?

可以,但每次调用会替换之前的 hook。如果需要保留之前的行为,先用 take_hook 取出旧 hook,在新 hook 中调用它。

问题四:hook 中可以再次 panic 吗?

技术上可以,但非常危险。如果 hook 中 panic,可能导致无限递归或进程直接 abort。hook 中应该使用防御性编程,避免任何可能失败的操作。

适用场景 ​

  • 错误日志:将 panic 信息记录到文件或日志系统
  • 错误监控:发送错误报告到监控平台
  • 调试辅助:格式化输出更友好的 panic 信息
  • 多线程服务:统一收集各线程的 panic 信息

注意事项 ​

  • set_hook 是全局的,所有线程共享同一个 hook
  • hook 闭包必须是 Send + Sync + 'static
  • 每次 set_hook 会替换之前的 hook
  • take_hook 取出当前 hook 并恢复默认
  • hook 中不要执行可能 panic 的操作
  • hook 在栈展开之前执行
  • 即使是 abort 模式,hook 仍然会执行
  • hook 内访问共享状态需要同步原语

总结 ​

Panic Hook 让你可以自定义 panic 发生时的处理行为。通过 std::panic::set_hook 设置一个接收 &PanicInfo 参数的闭包,在栈展开之前执行。PanicInfo 包含 panic 的消息(payload)和代码位置(location)。hook 是全局的,所有线程共享,要求 Send + Sync + 'static。可以用 take_hook 取出当前 hook 实现链式组合。常见用途包括错误日志记录、监控报警、友好错误输出等。hook 中应避免执行可能 panic 的操作,防止递归 panic。