注意：您必须启用 "fancy" crate 功能以获取类似于此处截图中的花哨报告输出。**您应该只在您的顶级 crate 中这样做，因为花哨功能会引入许多库可能不需要的依赖项。

use miette::{IntoDiagnostic, Result};
use semver::Version;

fn pretend_this_is_main() -> Result<()> {
    let version: Version = "1.2.x".parse().into_diagnostic()?;
    println!("{}", version);
    Ok(())
}

请注意：要获得具有所有漂亮颜色和箭头的花哨诊断渲染，您应该启用 fancy 功能安装 miette

miette = { version = "X.Y.Z", features = ["fancy"] }

另一种显示诊断的方法是使用调试格式化程序打印它们。实际上，这就是从 main 返回诊断所做的事情。要自己这样做，您可以编写以下内容

use miette::{IntoDiagnostic, Result};
use semver::Version;

fn just_a_random_function() {
    let version_result: Result<Version> = "1.2.x".parse().into_diagnostic();
    match version_result {
        Err(e) => println!("{:?}", e),
        Ok(version) => println!("{}", version),
    }
}

... 诊断代码 URL

miette 支持为单个诊断提供 URL。此 URL 将在支持的终端中显示为实际链接，如下所示

要使用此功能，您可以将 url() 子参数添加到您的 #[diagnostic] 属性

use miette::Diagnostic;
use thiserror::Error;

#[derive(Error, Diagnostic, Debug)]
#[error("kaboom")]
#[diagnostic(
    code(my_app::my_error),
    // You can do formatting!
    url("https://my_website.com/error_codes#{}", self.code().unwrap())
)]
struct MyErr;

此外，如果您正在开发库，并且您的错误类型是从 crate 的顶级导出的，则可以使用特殊的 url(docsrs) 选项而不是手动构造 URL。这将自动在 docs.rs 上创建一个链接到该诊断的链接，因此人们可以直接转到关于此诊断的（非常高质量和详细的！）文档

use miette::Diagnostic;
use thiserror::Error;

#[derive(Error, Diagnostic, Debug)]
#[diagnostic(
    code(my_app::my_error),
    // Will link users to https://docs.rs/my_crate/0.0.0/my_crate/struct.MyErr.html
    url(docsrs)
)]
#[error("kaboom")]
struct MyErr;

... 代码片段

除了其通用的错误处理和报告功能外，miette 还包括添加错误范围/注释/标签到您输出的功能。当错误与语法相关时，这非常有用，但您甚至可以使用它来打印您自己的源代码部分！

为了实现这一点，miette 定义了自己的轻量级 SourceSpan 类型。这是一个关联 SourceCode 的基本字节偏移量和长度，并且与后者一起，为 miette 提供了所有打印某些片段所需的信息！您还可以使用您自己的 Into<SourceSpan> 类型作为标签范围。

定义此类错误的简单方法是使用 derive(Diagnostic) 宏

use miette::{Diagnostic, SourceSpan};
use thiserror::Error;

#[derive(Diagnostic, Debug, Error)]
#[error("oops")]
#[diagnostic(code(my_lib::random_error))]
pub struct MyErrorType {
    // The `Source` that miette will use.
    #[source_code]
    src: String,

    // This will underline/mark the specific code inside the larger
    // snippet context.
    #[label = "This is the highlight"]
    err_span: SourceSpan,

    // You can add as many labels as you want.
    // They'll be rendered sequentially.
    #[label("This is bad")]
    snip2: (usize, usize), // `(usize, usize)` is `Into<SourceSpan>`!

    // Snippets can be optional, by using Option:
    #[label("some text")]
    snip3: Option<SourceSpan>,

    // with or without label text
    #[label]
    snip4: Option<SourceSpan>,
}

... 帮助文本

miette 为您提供了两种为错误提供帮助文本的方法

第一种是应用于结构体或枚举变体的 #[help()] 格式属性

use miette::Diagnostic;
use thiserror::Error;

#[derive(Debug, Diagnostic, Error)]
#[error("welp")]
#[diagnostic(help("try doing this instead"))]
struct Foo;

另一种是通过程序性地将帮助文本作为字段提供给您诊断

use miette::Diagnostic;
use thiserror::Error;

#[derive(Debug, Diagnostic, Error)]
#[error("welp")]
#[diagnostic()]
struct Foo {
    #[help]
    advice: Option<String>, // Can also just be `String`
}

let err = Foo {
    advice: Some("try doing this instead".to_string()),
};

... 严重级别

miette 提供了一种设置诊断严重级别的方法。

use miette::Diagnostic;
use thiserror::Error;

#[derive(Debug, Diagnostic, Error)]
#[error("welp")]
#[diagnostic(severity(Warning))]
struct Foo;

... 多个相关错误

miette 支持将多个错误收集到一个诊断中，并一起优雅地打印它们。

要这样做，请在您的 Diagnostic 类型中的任何 IntoIter 字段上使用 #[related] 标签

use miette::Diagnostic;
use thiserror::Error;

#[derive(Debug, Error, Diagnostic)]
#[error("oops")]
struct MyError {
    #[related]
    others: Vec<MyError>,
}

... 延迟源代码

有时在错误消息中添加源代码是有意义的。一个选项是使用 with_source_code() 方法来实现

use miette::{Diagnostic, SourceSpan};
use thiserror::Error;

#[derive(Diagnostic, Debug, Error)]
#[error("oops")]
#[diagnostic()]
pub struct MyErrorType {
    // Note: label but no source code
    #[label]
    err_span: SourceSpan,
}

fn do_something() -> miette::Result<()> {
    // This function emits actual error with label
    return Err(MyErrorType {
        err_span: (7..11).into(),
    })?;
}

fn main() -> miette::Result<()> {
    do_something().map_err(|error| {
        // And this code provides the source code for inner error
        error.with_source_code(String::from("source code"))
    })
}

此外，源代码也可以由包装类型提供。这对于与 related 结合使用特别有用，当需要同时发出多个错误时

use miette::{Diagnostic, Report, SourceSpan};
use thiserror::Error;

#[derive(Diagnostic, Debug, Error)]
#[error("oops")]
#[diagnostic()]
pub struct InnerError {
    // Note: label but no source code
    #[label]
    err_span: SourceSpan,
}

#[derive(Diagnostic, Debug, Error)]
#[error("oops: multiple errors")]
#[diagnostic()]
pub struct MultiError {
    // Note source code by no labels
    #[source_code]
    source_code: String,
    // The source code above is used for these errors
    #[related]
    related: Vec<InnerError>,
}

fn do_something() -> Result<(), Vec<InnerError>> {
    Err(vec![
        InnerError {
            err_span: (0..6).into(),
        },
        InnerError {
            err_span: (7..11).into(),
        },
    ])
}

fn main() -> miette::Result<()> {
    do_something().map_err(|err_list| MultiError {
        source_code: "source code".into(),
        related: err_list,
    })?;
    Ok(())
}

...基于诊断的错误源。

当在字段上使用 #[source] 属性时，通常来自 thiserror，并实现了 std::error::Error::source 方法。这在许多情况下都适用，但它是有损的：如果诊断的来源是另一个诊断，那么来源将被简单地视为一个 std::error::Error。

尽管这对现有的 reporters 没有影响，因为它们现在不会使用这些信息，但可能需要这些信息的 API 将无法访问这些信息。

如果您认为这些信息对用户来说很重要，您可以在 #[source] 旁边使用 #[diagnostic_source]。请注意，您可能不需要同时使用 两者

use miette::Diagnostic;
use thiserror::Error;

#[derive(Debug, Diagnostic, Error)]
#[error("MyError")]
struct MyError {
    #[source]
    #[diagnostic_source]
    the_cause: OtherError,
}

#[derive(Debug, Diagnostic, Error)]
#[error("OtherError")]
struct OtherError;

... 处理器选项

MietteHandler 是默认处理器，并且非常可定制。在大多数情况下，您可以使用 MietteHandlerOpts 来调整其行为，而不是回退到您自己的自定义处理器。

用法如下

miette::set_hook(Box::new(|_| {
    Box::new(
        miette::MietteHandlerOpts::new()
            .terminal_links(true)
            .unicode(false)
            .context_lines(3)
            .tab_width(4)
            .break_words(true)
            .build(),
    )
}))

有关您可以定制的详细信息，请参阅 MietteHandlerOpts 的文档！

... 动态诊断

如果您...

• ...不知道所有可能的错误
• ...如果需要序列化和反序列化错误，则可能希望使用 miette!、diagnostic! 宏或直接使用 MietteDiagnostic 来动态创建诊断。

let source = "2 + 2 * 2 = 8".to_string();
let report = miette!(
  labels = vec![
      LabeledSpan::at(12..13, "this should be 6"),
  ],
  help = "'*' has greater precedence than '+'",
  "Wrong answer"
).with_source_code(source);
println!("{:?}", report)

... 语法高亮

miette 可以配置以突出显示源代码片段中的语法。

要使用内置的突出显示功能，必须启用 syntect-highlighter 包特性。当此特性启用时，miette 将自动使用 syntect 包来突出显示你的 Diagnostic 的 #[source_code] 字段。

使用 syntect 进行语法检测是通过检查 SpanContents 特性上的2个方法来处理的。

• language() - 提供语言的名称作为字符串。例如，"Rust" 将指示 Rust 语法高亮。您可以通过 with_language 方法设置由 NamedSource 产生的 SpanContents 的语言。
• name() - 如果没有显式设置语言，则假设名称包含文件名或文件路径。高亮器将在名称的末尾检查文件扩展名并尝试从中猜测语法。

如果您想使用自定义高亮器，可以通过调用 with_syntax_highlighting 方法向 MietteHandlerOpts 提供自定义的 Highlighter 特性实现。有关更多详细信息，请参阅 highlighters 模块文档。

... 标签集合

当标签数量未知时，您可以使用一组 SourceSpan（或任何可以转换为 SourceSpan 的类型）。为此，将 collection 参数添加到 label 并使用任何可以迭代的类型作为字段。

#[derive(Debug, Diagnostic, Error)]
#[error("oops!")]
struct MyError {
    #[label("main issue")]
    primary_span: SourceSpan,

    #[label(collection, "related to this")]
    other_spans: Vec<Range<usize>>,
}

let report: miette::Report = MyError {
    primary_span: (6, 9).into(),
    other_spans: vec![19..26, 30..41],
}.into();

println!("{:?}", report.with_source_code("About something or another or yet another ...".to_string()));

如果想要为不同的标签使用不同的文本，则集合也可以是 LabeledSpan。没有文本的标签将使用 label 属性中的文本。

#[derive(Debug, Diagnostic, Error)]
#[error("oops!")]
struct MyError {
    #[label("main issue")]
    primary_span: SourceSpan,

    #[label(collection, "related to this")]
    other_spans: Vec<LabeledSpan>, // LabeledSpan
}

let report: miette::Report = MyError {
    primary_span: (6, 9).into(),
    other_spans: vec![
        LabeledSpan::new(None, 19, 7), // Use default text `related to this`
        LabeledSpan::new(Some("and also this".to_string()), 30, 11), // Use specific text
    ],
}.into();

println!("{:?}", report.with_source_code("About something or another or yet another ...".to_string()));

MSRV

此包需要 rustc 1.70.0 或更高版本。

鸣谢

miette 并非空穴来风。它对各种其他项目和它们的作者给予了巨大的信用。

• anyhow 和 color-eyre：这两个极具影响力的错误处理库推动了应用级错误处理和错误报告的体验。《miette》的 Report 类型是对它们 Report 类型的一个非常粗略的尝试。
• 用于设置库级错误定义标准的 thiserror，以及作为 miette 的 derive 宏的灵感来源。
• rustc 和 @estebank 对于他们在编译器诊断方面的一流工作。
• 为使诊断看起来更美观，ariadne 发挥了推动作用！

许可证

miette 在 Apache 许可证 2.0 下发布给 Rust 社区。

它还包括从 eyre 和 thiserror（同样在 Apache 许可证下）以及从 ariadne（MIT 许可证）中获取的代码。一些代码来自 ariadne。