effect-smol 错误处理入门TaggedErrorClass 与 Effect.catchTag 完全指南【免费下载链接】effect-smolCore libraries and experimental work for Effect v4项目地址: https://gitcode.com/GitHub_Trending/ef/effect-smol在 Effect v4 核心库effect-smol中错误处理不再依赖字符串或简单的try/catch而是围绕TaggedErrorClass带标签的错误类与Effect.catchTag按标签捕获这套类型安全机制展开。这篇入门指南将带你在 5 分钟内容看懂如何用 Schema 定义结构化错误、如何按_tag精准恢复以及 v4 中错误 API 的完整改动。为什么需要带标签的错误 ️传统写法里判断错误类型往往靠instanceof或字符串比较类型容易丢失。effect-smol 的解法定义阶段用Schema.TaggedErrorClass声明错误类自动获得一个只读的_tag判别字段和字段校验能力。恢复阶段用Effect.catchTag按_tag精确匹配错误只处理你想要的那一类其余错误继续向上传播。这就像给每个错误贴上快递单号恢复逻辑按单号分拣既安全又直观。定义错误TaggedErrorClass 三步走TaggedErrorClass是Schema模块导出的构造函数位于 packages/effect/src/Schema.ts。用法只需三步import { Schema } from effect export class ParseError extends Schema.TaggedErrorClassParseError()(ParseError, { input: Schema.String, message: Schema.String }) {}第一个参数ParseError就是_tag的值用于后续匹配第二个参数用 Schema 描述错误携带的字段构造时自动校验实例上还会自动带name属性方便调试日志展示。一个更完整的示例含两个错误类可参考官方文档中的示例源码ai-docs/src/01_effect/04_errors/01_error-handling.ts。精准恢复Effect.catchTag 的基本用法Effect.catchTag定义于 packages/effect/src/Effect.ts它通过_tag字段匹配错误只会捕获指定标签的错误其他错误原样保留在错误通道中——这是类型安全恢复的关键。import { Effect } from effect // 只处理 ReservedPortErrorParseError 仍会向外抛出 const recovered loadPort(80).pipe( Effect.catchTag(ReservedPortError, (_) Effect.succeed(3000)) )它也支持一次捕获多个标签传入字符串数组即可const recovered loadPort(80).pipe( Effect.catchTag([ParseError, ReservedPortError], (_) Effect.succeed(3000)) )如果还想加一道兜底可以再接Effect.catch捕获所有可恢复错误注意catch不会捕获不可恢复的 defect那需要catchCause。多个错误一次分流Effect.catchTags当错误通道里有好几种标签、且每种需要不同处理时Effect.catchTags见 packages/effect/src/Effect.ts可以按对象形式一次性分流const userOrFallback fetchUser(123).pipe( Effect.catchTags({ ValidationError: (error) Effect.succeed(Validation failed: ${error.message}), NetworkError: (error) Effect.succeed(Network failed, status: ${error.statusCode}) }) )完整示例见 ai-docs/src/01_effect/04_errors/10_catch-tags.ts。进阶v4 还新增了Effect.catchReason/Effect.catchReasons用于处理错误内部嵌套的reason字段例如 AI 调用错误中区分限流与超配额示例见 ai-docs/src/01_effect/04_errors/20_reason-errors.ts。v4 错误 API 重命名速查表 如果你从 v3 升级而来catch系列函数有大量改名完整对照可查阅 migration/error-handling.mdv3 写法v4 写法说明Effect.catchAllEffect.catch捕获所有可恢复错误Effect.catchAllCauseEffect.catchCause连 defect 也能恢复Effect.catchAllDefectEffect.catchDefect仅恢复 defectEffect.catchSomeEffect.catchFilter改用 Filter 模块判断Effect.catchTag/catchTags保持不变本项目的主角 ✨小结记住这三行心法定义错误→Schema.TaggedErrorClass自动_tag Schema 校验精确恢复→Effect.catchTag单个或多个标签全量分流→Effect.catchTags最后用Effect.catch兜底。配套学习资料错误处理入门文档ai-docs/src/01_effect/04_errors/index.md迁移指南总入口MIGRATION.md【免费下载链接】effect-smolCore libraries and experimental work for Effect v4项目地址: https://gitcode.com/GitHub_Trending/ef/effect-smol创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考