cats-mtl-typed-errors

Cats MTL 类型化错误（Scala）

快速入门

• 定义领域错误类型；根据上下文，它可以继承 Throwable，也可以不继承。
• 在可能引发错误的函数中使用 Cats MTL Raise[F, E]。
• 使用 Handle.allow/rescue（Scala 3）或 Handle.allowF（Scala 2）引入作用域内的错误能力，并像使用 try/catch 一样处理错误。
• 优先使用 Cats MTL，而不是 IO[Either[E, A]]，并避免使用 EitherT[IO, E, A]；在 API 边界，返回 Either[E, A] 的纯函数没有问题。
• F[_] 是可选的：可根据项目需求编写特定于 IO 的代码，也可以保留 F[_] 以支持多态。

工作流

1. 将领域错误建模为密封 ADT（Scala 2）或枚举（Scala 3）
2. 对于可能引发错误的有效应代码，要求提供 Raise[F, E]（以及 Monad[F] 或 Applicative[F]）。
3. 使用 .raise 引发错误，并使用 pure 返回成功值。
4. 在边界处，使用 Handle.allow（Scala 3）或 Handle.allowF（Scala 2）创建一个允许引发错误的作用域。
5. 使用 .rescue 结束作用域，并显式处理每种错误情况。
6. 通过保持在单一函子错误通道中，保留 Cats Effect 的资源与并发语义。

应用模式

• 签名中的类型化错误：将错误类型参数 E 视为函数签名中的已检查异常通道。
• 作用域内的错误能力：要求可能失败的函数提供 Raise[F, E]；如果还需要恢复，则使用 Handle[F, E]。
• Scala 3 易用性：优先使用 using 和搭配 allow 的上下文函数，类型推断效果会好得多。
• Scala 2 兼容性：使用 allowF 和显式隐式参数；代码中预计会有更多花括号和显式类型。
• 与纯代码互操作：使用纯 Either[E, A] 进行解析/验证，并在需要时提升到 F。
• 避免转换器堆栈：不要仅为了获得类型化错误通道而使用 EitherT；Cats MTL 提供的能力无需堆栈。
• 避免密封类型层层继承：使用组合（包装案例类）而非密封继承链来建模错误层次结构。

参考资料

• 加载 references/custom-error-types.md，了解详细指南、Scala 2/3 语法，以及 Typelevel 文章中的设计依据。