terrors - Rust 错误处理库

错误处理意味着处理一组可能的错误类型，移除可在本地解决的错误，然后如果剩余的错误集不在本地关注范围内，就将其传播给调用者。调用者不应接收被调用者的本地错误。

原则

• 错误类型应该精确。
  • terrors::OneOf 通过创建精确的可能错误集来解决这个问题：
    • 指定时摩擦力低
    • 通过特定错误处理程序缩小范围的摩擦力低
    • 扩大范围以传递到堆栈上层的摩擦力低
• 错误处理应遵循单一责任原则
  • 如果系统中的每个错误都分散到其他地方，就不清楚在哪里处理它们的责任。
• 没有宏。
  • 用户不应该学习每个宏所带来的新的错误处理DSL。

示例

use terrors::OneOf;

let one_of_3: OneOf<(String, u32, Vec<u8>)> = OneOf::new(5);

let narrowed_res: Result<u32, OneOf<(String, Vec<u8>)>> =
    one_of_3.narrow();

assert_eq!(5, narrowed_res.unwrap());

OneOf 还可以扩展到一个超集，在编译时检查。

use terrors::OneOf;

struct Timeout;
struct AllocationFailure;
struct RetriesExhausted;

fn allocate_box() -> Result<Box<u8>, OneOf<(AllocationFailure,)>> {
    Err(AllocationFailure.into())
}

fn send() -> Result<(), OneOf<(Timeout,)>> {
    Err(Timeout.into())
}

fn allocate_and_send() -> Result<(), OneOf<(AllocationFailure, Timeout)>> {
    let boxed_byte: Box<u8> = allocate_box().map_err(OneOf::broaden)?;
    send().map_err(OneOf::broaden)?;

    Ok(())
}

fn retry() -> Result<(), OneOf<(AllocationFailure, RetriesExhausted)>> {
    for _ in 0..3 {
        let Err(err) = allocate_and_send() else {
            return Ok(());
        };

        // 如果遇到 Timeout 就继续重试，
        // 但将分配问题传递给调用者。
        match err.narrow::<Timeout, _>() {
            Ok(_timeout) => {},
            Err(one_of_others) => return Err(one_of_others.broaden()),
        }
    }

    Err(OneOf::new(RetriesExhausted))
}

如果类型集中的所有类型都实现了相应的 trait，OneOf 也会实现 Clone、Debug、Display 和/或 std::error::Error：

use std::error::Error;
use std::io;
use terrors::OneOf;

let o_1: OneOf<(u32, String)> = OneOf::new(5_u32);

// 如果类型集中的所有类型都实现了 Debug，则实现 Debug
dbg!(&o_1);

// 如果类型集中的所有类型都实现了 Display，则实现 Display
println!("{}", o_1);

let cloned = o_1.clone();

type E = io::Error;
let e = io::Error::new(io::ErrorKind::Other, "wuaaaaahhhzzaaaaaaaa");

let o_2: OneOf<(E,)> = OneOf::new(e);

// 如果类型集中的所有类型都实现了 std::error::Error，则实现 std::error::Error
dbg!(o_2.description());

OneOf 还可以转换为所有权或引用的枚举形式：

use terrors::{OneOf, E2};

let o_1: OneOf<(u32, String)> = OneOf::new(5_u32);

match o_1.as_enum() {
    E2::A(u) => {
        println!("处理引用 {u}: u32")
    }
    E2::B(s) => {
        println!("处理引用 {s}: String")
    }
}

match o_1.to_enum() {
    E2::A(u) => {
        println!("处理所有权 {u}: u32")
    }
    E2::B(s) => {
        println!("处理所有权 {s}: String")
    }
}

动机

论文《简单测试可以防止大多数关键故障：对分布式数据密集型系统生产故障的分析》 是一个宝库，包含了大量有趣的统计数据，揭示了与系统故障相对应的软件模式。 这是我最喜欢的一个：

几乎所有（92%）的灾难性系统故障
都是由于软件中明确信号的非致命错误
处理不当造成的。

我们的系统崩溃是因为我们没有处理好错误。我们在发出错误信号方面做得很好，但我们需要真正处理它们。

当我们编写 Rust 时，我们往往会遇到各种不同的错误类型。有时我们需要将多个可能的错误放入一个容器中，然后从函数返回，其中调用者或间接调用者预期会处理出现的特定问题。 随着代码库的增长，这些情况会越来越多。 虽然在一两个地方编写包含精确错误集合的自定义枚举并不费力，但大多数人为了减少传播错误类型的工作量，通常会采用以下两种策略之一：

• 一个大型的顶级枚举，包含整个代码库中产生的错误变体，随着时间推移会越来越大，削弱了使用穷尽模式匹配来确保局部问题不会冒泡到栈上的能力。
• 一个易于将错误转换的装箱trait，但它隐藏了内部可能包含的实际信息。你不知道它来自哪里，也不知道它将去向何处。

随着这些错误容器所包含的不同源错误类型数量的增加，容器向遇到它的人传达的信息量就会减少。容器实际包含什么变得越来越不清楚。随着类型精确度的降低，人们推理其中任何特定问题应在何处处理的能力也随之下降。

我们必须提高错误类型的精确度。

人们不会为每个可能只返回某些错误子集的函数编写精确的枚举，因为这样会产生大量只在一两个地方使用的小型枚举类型。这种痛苦驱使人们使用过于宽泛的错误枚举或过于平滑的装箱动态错误trait，降低了他们处理错误的能力。

酷炫功能

这个 crate 围绕 OneOf 构建，它作为一种匿名枚举形式，可以以类似 TypeScript 等语言用户熟悉的方式进行缩小。随着单个错误被剥离和处理，我们的错误容器需要变得更小，如果局部问题不存在，则留下减少的剩余可能错误类型。

它的酷炫之处在于它建立在一个类型级别的异构可能错误类型集合之上，其中只有一个实际值存在于不同的可能性中。

与其使用一个巨大的混乱枚举或装箱trait对象（永远不清楚它实际包含什么，导致你永远不处理其中的个别问题），这个想法是你可以拥有一个最小化的实际错误类型集，可以在栈中传递。

这种类型级别的可能性集合的好处是，可以剥离任何特定类型，同时在缩小失败时缩小剩余类型。缩小和扩大都基于编译时错误类型集检查。

权衡

在我职业生涯的大部分时间里，我一直努力避免类型级编程，因为编译错误会导致令人困惑的错误消息。这些复杂的类型检查失败会产生难以理解的错误，通常需要几分钟才能理解。

我努力避免让 terrors 的用户过多地接触底层类型机制的尖锐边缘，但如果源和目标类型集不满足正确方向上的 SupersetOf trait（取决于是调用 narrow 还是 broaden），那么错误可能不会特别容易阅读。只需知道，错误几乎总是意味着超集关系不像要求的那样成立。

展望未来，我相信大多数必需的trait可以通过利用异构类型集 Cons 链和更人性化的类型元组之间存在的双向类型映射，以暴露给用户看起来更像 (A, B) does not implement SupersetOf<(C, D), _> 而不是 Cons<A, Cons<B, End>> does not implement SupersetOf<Cons<C, Cons<D, End>>> 的错误的方式来实现。

特别感谢

推理错误类型集的大部分复杂类型级逻辑直接受到 frunk 的启发。多年来，我一直在思考像 OneOf 这样的数据结构的可行性，经常认为它是不可能的，直到我终于有了一个长周末可以深入研究。经过多次失败的尝试后，我最终看到了 lloydmeta（frunk 的作者）写的一篇文章，讲述了 frunk 如何在异构列表结构的上下文中处理几个相关问题。尽管我使用 Rust 超过 10 年，但那篇文章教会了我大量关于如何以有趣的方式使用该语言的类型系统来解决非常实际的需求。特别是，该博客文章中关于如何以递归方式实现 trait（这种方式在其他函数式语言中很常见）的总体观点，是我在使用 Rust 的前十年中没有意识到可能的缺失原语。非常感谢创建 frunk 并向世界讲述你是如何做到的！