errgo

生成内联的 enum 错误变体。

对anyhow 的一种稍微类型安全的改进，其中每个特定错误都可通过调用者处理。旨在与其他crate（如strum 或 thiserror）良好地配合使用。

这个crate是为了帮助封装C API而编写的 - 例如，将错误代码转换为可处理的消息。实际上不应该用于库API入口点 - 一个经过深思熟虑的顶级错误类型可能既易于阅读又具有向前兼容性。建议阅读《std::io::Error》的研究或简单地将所有生成的结构体设置为 pub(crate)。

use errgo::errgo;

#[errgo]
fn shave_yaks(
    num_yaks: usize,
    empty_buckets: usize,
    num_razors: usize,
) -> Result<(), ShaveYaksError> {
    if num_razors == 0 {
        return Err(err!(NotEnoughRazors));
    }
    if num_yaks > empty_buckets {
        return Err(err!(NotEnoughBuckets {
            got: usize = empty_buckets,
            required: usize = num_yaks,
        }));
    }
    Ok(())
}

在内部，会生成如下结构体

enum ShaveYaksError { // name and visibility are taken from function return type and visibility
    NotEnoughRazors,
    NotEnoughBuckets {
        got: usize,
        required: usize,
    }
}

请注意，结构体定义放置在函数体上方，这意味着您不能在 impl 块中的函数上使用 errgo - 您必须将函数体移动到外部作用域，并在impl块中调用它。

重要的是，您可以在生成的结构体上派生，并且还可以传递属性，这允许您使用如 thiserror 或 strum 这样的crate。有关宏接受的其它参数，请参阅errgo 文档。

#[errgo(derive(Debug, thiserror::Error))]
fn shave_yaks(
    num_yaks: usize,
    empty_buckets: usize,
    num_razors: usize,
) -> Result<(), ShaveYaksError> {
    if num_razors == 0 {
        return Err(err!(
            #[error("not enough razors!")]
            NotEnoughRazors
        ));
    }
    if num_yaks > empty_buckets {
        return Err(err!(
            #[error("not enough buckets - needed {required}")]
            NotEnoughBuckets {
                got: usize = empty_buckets,
                required: usize = num_yaks,
            }
        ));
    }
    Ok(())
}

这将生成以下内容

#[derive(Debug, thiserror::Error)]
enum ShaveYaksError {
    #[error("not enough razors!")]
    NotEnoughRazors,
    #[error("not enough buckets - needed {required}")]
    NotEnoughBuckets {
        got: usize,
        required: usize,
    }
}

并且 err! 宏调用被替换为结构体实例化 - 不论它们在函数体中的位置如何！

如果您需要在函数中重用相同的变体，只需使用正常的构造语法即可。

#[errgo]
fn foo() -> Result<(), FooError> {
    fallible_op().map_err(|e| err!(IoError(io::Error = e)));
    Err(FooError::IoError(todo!()))
}