用途:该技能刻意保持窄范围,不试图教授完整 Effect,而是面向应用层 Effect 代码,例如路由处理器、服务端函数、功能编排、异步工作流,以及受益于类型化错误和显式执行边界的业务逻辑。它不是完整的 Effect 参考;Layer、Context、Schema、Stream、并发原语和服务架构等更广 API 需查阅 references/official-docs.md 中链接的官方文档。
适用时机:把大量使用 Promise 的应用逻辑转换为 Effect;把抛出的错误重构为类型化领域失败;编写多步服务端或功能工作流;在 Effect 程序内加入日志与恢复;统一 Effect.runPromise 风格执行发生的位置。不要把它当作库中每个模块的通用 Effect 最佳实践指南,它专门针对应用模式。
默认应用模式:将程序建模为 Effect.Effect<Success, Error, Requirements>;用 Effect.gen 做多步编排;用 Effect.try / Effect.tryPromise 包裹不安全的同步或异步边界;用 Data.TaggedError 表示预期失败;把日志和恢复保留在 Effect 管道内;只在框架边界执行程序。
延伸阅读:references/core-patterns.md 提供该技能所依据的首选编码模式;references/official-docs.md 用于任务需要超出此窄范围的应用模式之外的 Effect API 时。
常见错误:对预期的领域失败抛出原始异常;在库辅助函数深处调用 Effect.runPromise;在 Effect 优先代码中使用 console.log 而非 Effect.log*;把所有失败隐藏在一个通用错误类型后面;在基本 effectful 边界尚未理清前就使用高级抽象。