color-eyre

一个用于处理panic和eyrecrate的错误报告处理器，用于生成各种错误的多彩、一致和格式化的错误报告。

TLDR

color_eyre可以帮助您构建如下错误报告

设置

将以下内容添加到您的toml文件中

[dependencies]
color-eyre = "0.6"

并安装panic和错误报告处理器

use color_eyre::eyre::Result;

fn main() -> Result<()> {
    color_eyre::install()?;

    // ...
    # Ok(())
}

禁用跟踪支持

如果您不打算使用tracing_error和SpanTrace，您可以禁用跟踪集成以减少未使用的依赖项

[dependencies]
color-eyre = { version = "0.6", default-features = false }

默认禁用SpanTrace捕获

color-eyre默认捕获span跟踪。这是因为SpanTrace捕获比Backtrace捕获便宜得多。然而，与回溯一样，span跟踪对于调试应用程序非常有用，并且默认禁用span跟踪捕获以减少开发中的噪音并不少见。

要禁用span跟踪捕获，您必须显式设置一个控制SpanTrace捕获的env变量为"0"

if std::env::var("RUST_SPANTRACE").is_err() {
    std::env::set_var("RUST_SPANTRACE", "0");
}

提高调试构建的性能

在调试模式下，color-eyre 的表现明显比 eyre 差。这是因为 eyre 使用的是 std::backtrace::Backtrace 而不是 backtrace::Backtrace。std 版本的 backtrace 是预编译并进行了优化的，这意味着无论是否处于调试模式，对于捕获 backtrace 的开销影响不大，它总是在数十毫秒内完成。然而，backtrace::Backtrace 的调试版本却没那么幸运，捕获 backtrace 的时间是其 std 对应版本的十倍以上。

Cargo 配置文件覆盖 可以用来减轻这个问题。通过配置项目始终以优化方式构建 backtrace，你应该可以获得与使用 eyre 时相同的 color-eyre 性能。要做到这一点，请将以下内容添加到您的 Cargo.toml 文件中

[profile.dev.package.backtrace]
opt-level = 3

功能

多级报告格式详细程度

color-eyre 提供了 3 种不同的报告格式来格式化捕获的 SpanTrace 和 Backtrace，包括最小化、简短和完整。以下是 examples/usage.rs 生成的输出示例片段

在未设置 RUST_LIB_BACKTRACE 的情况下运行 cargo run --example usage 将生成类似的最小化报告

运行 RUST_LIB_BACKTRACE=1 cargo run --example usage 告诉 color-eyre 使用简短格式，该格式除了捕获错误信息外，还会捕获 backtrace::Backtrace

最后，运行 RUST_LIB_BACKTRACE=full cargo run --example usage 告诉 color-eyre 使用完整格式，除了上述信息外，还会尝试包括错误起源的源代码行，前提是它能在磁盘上找到它们。

通过 Section 特性为错误报告添加自定义 Section

section 模块提供了用于向错误报告中添加额外部分的辅助函数。部分与错误消息不同，并且独立于错误链显示。以下是一个示例，展示了如何添加部分来包含来自失败命令的 stderr 和 stdout，该示例来自 examples/custom_section.rs

use color_eyre::{eyre::eyre, SectionExt, Section, eyre::Report};
use std::process::Command;
use tracing::instrument;

trait Output {
    fn output2(&mut self) -> Result<String, Report>;
}

impl Output for Command {
    #[instrument]
    fn output2(&mut self) -> Result<String, Report> {
        let output = self.output()?;

        let stdout = String::from_utf8_lossy(&output.stdout);

        if !output.status.success() {
            let stderr = String::from_utf8_lossy(&output.stderr);
            Err(eyre!("cmd exited with non-zero status code"))
                .with_section(move || stdout.trim().to_string().header("Stdout:"))
                .with_section(move || stderr.trim().to_string().header("Stderr:"))
        } else {
            Ok(stdout.into())
        }
    }
}

这里有一个函数，如果命令失败退出，则创建一个报告，表明失败，并附加两个部分，一个用于 stdout，一个用于 stderr。

运行 cargo run --example custom_section 展示了这些部分如何包含在输出中

只有Stderr:部分实际上被包含。由于cat命令失败，所以stdout为空，并在最终报告中被跳过。这给我们一个简洁的错误报告，明确指出尝试了什么以及如何失败。

将多个错误汇总到一个报告中

对于批处理任务运行器或解析器等程序来说，返回具有多个来源的错误并不少见。尽管目前版本的错误特质并不很好地支持此用例，但有人正在努力改进这个功能。

然而，目前有一种方法可以在错误特质之外组合错误。color-eyre通过其Section特质在其错误报告中支持这种组合。

有关如何汇总错误的示例，请查看examples/multiple_errors.rs。

为设置自定义过滤器和其他功能而自定义color-backtrace

对于回溯和跨度跟踪的格式化打印实际上不是由color-eyre提供的，而是由其依赖项color-backtrace和color-spantrace提供的。特别是color-backtrace具有许多比color-eyre导出更多的功能，例如自定义配色方案、panic钩子以及自定义框架过滤器。当与color-eyre结合使用时，自定义框架过滤器特别有用，因此为了启用它们的用法，我们提供了install fn，用于设置具有自定义过滤器的自定义BacktracePrinter。

有关如何设置自定义过滤器的示例，请查看examples/custom_filter.rs。

许可证