可以通过属性参数更改这些默认行为。

属性参数

可能的属性参数包括：tag、attach、attach_lazy、closures、async_blocks、skip、debug_skip、debug_with 和 debug_non_copyable。

有关如何使用它们的详细信息，请参阅文档。

标记错误

如上例所示，您可以使用 _tag 标记错误，并使用 tagged 和 tagged_nested 检测标记。

struct MyTag;

#[oofs]
fn application_level() -> Result<(), Oof> {
    if let Err(e) = source() {
        if e.tagged_nested::<MyTag>() {
            ...handle for this tag
        } else if e.tagged_nested::<OtherTag>() {
            ...handle for this tag
        } else {
            ...
        }
    }
}

...

#[oofs]
fn source() -> Result<(), Oof> {
    some_fn()._tag::<MyTag>()?;

    Ok(())
}

这允许您将错误分类到不同的标记组中，并相应地处理它们。与在每个嵌套函数调用中匹配每个枚举变体相比，这提供了更好的错误处理体验。

请注意，您还可以使用多个不同的标记标记错误。

我选择类型作为标记，因为类型小、可读且唯一。 String 或 usize 可能会意外地产生重复的值。

附加自定义上下文

在某个时候，您可能会发现生成的上下文信息不足。毕竟，它只显示了失败的调用及其传入的参数。它不会捕获所有其他可能的上下文信息。

您可以使用 _attach 和 _attach_lazy 方法将您自己的上下文信息附加到错误中。

#[oofs]
fn outer_fn() -> Result<(), Oof> {
    let x = 123usize;
    let y = std::time::Instant::now();

    "hello world"
        .parse::<usize>()
        ._attach(&x)
        ._attach(&y)?;

    Ok(())
}

以上将打印以下错误

$0.parse() failed at `oofs/tests/basic.rs:10:10`

Parameters:
    $0: &str = "hello world"

Attachments:
    0: 123
    1: Instant { t: 11234993365176 }

Caused by:
    invalid digit found in string

_attach 接受任何实现 std::fmt::Debug 的类型。

_attach_lazy，另一方面，接受任何返回实现 ToString 的闭包。

它可以是一个类似 &str 的东西，例如 ._attach_lazy(|| "some context")，或者类似 String 的东西，例如 ._attach_lazy(|| format!("some context {:?}", x)) 的字符串，或者需要一些工作才能显示的某些函数，例如 ._attach_lazy(|| serde_json::to_string(&x))。

返回自定义错误

在某个时候，你还需要返回自定义错误。

对于这些情况，你有一些选项：oof!(...)、wrap_err(_)、ensure!(...) 和 ensure_eq!(...)。

• oof!(...)：这与 anyhow! 或 eyre! 很相似；你像对 println! 一样将输入到宏中。这返回一个 Oof 结构体，你可以在返回的 Oof 上调用方法，如

  return oof!("my custom error").tag::<MyTag>().attach(&x).into_res();
  

  into_res() 将 Oof 包装到 Result::Err(_) 中。

• wrap_err(_)：这是一个包装自定义错误和 Oof 的函数。

  return wrap_err(std::io::Error::new(std::io::ErrorKind::Other, "Some Error")).tag::<MyTag>().into_res();
  

  into_res() 将 Oof 包装到 Result::Err(_) 中。

• ensure!(...)：这与其他很多库类似，但有一些细微的差异。

  可选地，你可以输入自定义上下文消息，例如 format!(...)。

  此外，你也可以可选地提供括号内的标签和属性。

  ensure!(false, "custom context with value {:?}", x, {
    tag: [MyTag, OtherTag],
    attach: [&y, "attachment", Instant::now()],
    attach_lazy: [|| serde_json::to_string(&y), || format!("lazy attachment {}", &z)]
  });
  

• ensure_eq!(...)：这与其他很多库类似，但有一些细微的差异。

  可选地，你可以输入自定义上下文消息，例如 format!(...)。

  此外，你也可以可选地提供括号内的标签和属性。

  ensure_eq!(1u8, 2u8, "custom context with value {:?}", x, {
    tag: [MyTag, OtherTag],
    attach: [&y, "attachment", Instant::now()],
    attach_lazy: [|| serde_json::to_string(&y), || format!("lazy attachment {}", &z)]
  });
  

功能

• location (默认值: true): 启用打印失败代码的位置。

• debug_non_copyable_disabled (默认值: false): 禁用调试不可复制的函数参数。

  默认行为是在调试模式下每次调用之前即时加载不可复制参数的调试字符串，但在发布模式下禁用。

• debug_non_copyable_full (默认值: false): 即使在发布模式下，也启用即时加载不可复制参数的调试字符串。

关于此库的注意事项/限制

关于 #[oofs] 属性

• #[oofs] 生成并注入所有具有 ? 操作符的语句和表达式的上下文。

• return Err(...) 或不带分号的最后一个表达式不会注入上下文。

• 如果方法接收者是变量（即 x.some_method()），或变量的字段（即 x.field.some_method()），则不会显示 x 或 x.field 的值。这是因为无法在宏中确定此接收者是引用、可变引用还是拥有变量。

  • 对于这些情况，您可以将变量附加如下 x.some_method()._attach(&x) 来显示错误中的 x 的值。

关于 Oof 错误结构体

• Oof 未实现 From<E> where E: std::error::Error，因此必须通过属性宏构建。因此，如果不包含 #[oofs]，则会导致编译错误；这是故意的，因为这将吸引用户的注意并迫使他们包含属性。

• 与 anyhow::Error 或 eyre::Report 不同，Oof 实现了 std::error::Error。这很棒，因为它使其与这些装箱错误类型兼容。例如，这可以工作

  #[oofs]
  fn outer_fn() -> Result<(), anyhow::Error> {
      inner_fn()?;
      Ok(())
  }
  

  它之所以可以工作，是因为 ? 操作符会隐式地将 Oof 转换为 anyhow::Error。

关于下划线方法如 ._tag() 和 ._attach(_)

在上面的基本示例中，您可能已经注意到所有用于 oof 的方法都以下划线开头；您可以称它们为 '元方法'，因为它们不影响逻辑，只影响返回的结果。

这是因为宏必须有一种方法来区分功能方法和元方法。这是因为宏也会尝试将这些元方法作为显示方法链的一部分，像 _attach(x) 这样的方法在 Parameters 和 Attachments 部分中会显示两次。

一开始这可能会让人感到困扰和不自然；对我也是如此。但是尝试过后，我习惯了它；现在我认为我喜欢它，因为可以轻松地区分功能方法和元方法。

我为带来的不便表示歉意，并请告诉我是否有更好的处理方式。

调试不可复制的参数

在创建库时的一个痛点是在编译时懒加载可复制参数的值，并立即加载不可复制参数的值。我找到了一种使用酷炫的Rust技巧来实现这一点的办法。

现在，默认行为应该是始终立即加载不可复制参数的值吗？这可能会带来不必要的性能开销，因为它会在非错误情况下加载它们。

作为妥协，我让它这样：在调试模式下，将立即加载不可复制参数的值；而在发布模式下，则不会加载不可复制参数的值。

您可以使用功能 debug_non_copyable_disabled 和 debug_non_copyable_full 来更改此行为。

debug_non_copyable_disabled 将禁用即使在调试模式下也加载不可复制参数的值。 debug_non_copyable_full 将允许即使在发布模式下也加载不可复制参数的值。

与 #[async_trait] 的兼容性

#[async_trait] 解析并将特质中 fn 的 async fn 转换为 fn -> Box<Future<Output = Result<...>>>. 由于 #[oofs] 默认情况下只将上下文注入应用到返回 Result<_, _> 的方法上，因此一旦应用了 #[async_trait]，就不会再应用注入。