SuperAPI AI 工具集

effect-ts

通用与其它

查看项目

更新于 10-16 09:29

技能介绍

用途:在编写或评审 Effect(Effect-TS)代码时提供设计原则与参考模式,覆盖服务定义、Layer 纪律化组合、尽量晚地逃出 Effect 运行时、将命令式代码转换为错误通道、从 Schema 派生类型,以及用 @effect/vitest 测试。每条规则先给出使其成立的机制,再给出修正方式。该技能只覆盖构建在 TypeScript 之上的 Effect 专属部分,基础编译器配置、泛型与工具类型属于 typescript-ecosystem。

版本:已对照 Effect 3.19.x、@effect/vitest 0.25.x、vitest 3.2.x 验证。Effect.Service、Layer.provide/provideMerge/merge/mergeAll、Effect.scoped、TestClock、Schema.Struct 在 3.x 线稳定。所有内容从单一 effect 包导入,测试绑定来自 @effect/vitest。Effect 2.x 及 pre-3.x 教程早于 Effect.Service 与当前 Schema 位置,不要跨大版本混合使用。版本相关主张应先查当前文档再断言。

服务定义:Effect.Service 是 tag 加默认 Layer 的语法糖,从标识符字符串生成 tag,用构造函数(effect/scoped/sync/succeed)构建实现,并暴露 .Default Layer。需要强制调用方提供实现、不应假设默认值时使用 Context.Tag 加 Layer.effect。四个构造函数键的差异在于接受什么、何时运行:succeed 接受已完成的普通对象,sync 接受 thunk,effect 接受 Effect,scoped 接受需要 Scope 的 Effect;后三者都在 Layer 构建时运行。succeed 不会调用传入的函数,按工厂函数使用会存下函数本身。同步有状态构建用 sync: () => impl 或 effect: Effect.sync(() => impl)。需要获取并释放资源(连接、监听器、定时器)的服务用 scoped,并用 Effect.acquireRelease 将获取绑定到 Scope。

Layer 组合:Layer.provide 用外层构建内层并消耗外层,不出现在结果输出类型中;provideMerge 同样但保留被提供的服务在输出中;merge/mergeAll 只是并列组合,输出是输出与需求的并集,不做接线。若 B 依赖 A,应写 B.pipe(Layer.provide(A)),不要用 mergeAll(A, B)。Effect.scoped 应放在 layer 提供管线之外,先 Effect.provide 再 scoped。记忆化是按提供图而非按 layer 值,同一 layer 在两个点提供会被构建两次,产生两个服务实例,拥有单例资源的服务要只在组合中一个点提供。Effect.provide 每次迭代并非免费,不要在每帧或每请求的处理路径内应用,应在程序边缘一次性解析服务。

尽量晚逃出运行时:每次 Effect.runPromise/runSync 都越过边界,放弃类型化错误、中断、结构化并发与调度。把外部回调一次性桥接进 Effect(如入队),再用单个分叉 fiber 在 Effect 内处理;边界处优先 Effect.runFork 而非 runPromise,并附加 Effect.catchAllCause 记录失败。

描述与执行:Effect 是描述。描述之外求值的内容在构建时只运行一次,其值冻结进之后每次执行;描述之内每次执行都会重跑。长运行 fiber:Effect.repeat 与 Effect.forever 在首次失败即终止,重复体应类型为 Effect<A, never>;catchAll 不捕获缺陷,长循环应用 catchAllCause;背压选择即队列选择,实时生产者不可减速时用 dropping/sliding;fork 守护进程后调用 Fiber.join 会永不返回;等待电平触发条件会忙等空转,应等待边沿。

限制:资料仅覆盖上述 Effect 专属表面,未提供完整安装命令、收费、价格与平台信息;具体版本的 API 细节需以官方文档为准。