Build Effect-TS v3 是一个面向 Effect-TS v3(effect@3.x)的 TypeScript 开发技能,用于构建生产级应用。其核心模型为 Effect<A, E, R>——一种惰性、带类型、不可变的工作描述;服务与 Layer 承载依赖;Schema 负责边界校验;fibers 提供结构化并发;Stream 承载基于拉取的异步数据。生态覆盖 @effect/platform、@effect/sql(含 11 个驱动包)、@effect/rpc、@effect/cli、@effect/vitest、@effect/opentelemetry,以及用于 React 的 @effect-atom/atom-react。
适用场景:构建、重构、调试或测试 Effect-TS v3 代码;实现类型化 tagged error、服务与 Layer、fibers、streams、缓存、调度与可观测性;使用 Effect.gen(function*() { yield* … })、class X extends Effect.Service<X>()(...)、class E extends Schema.TaggedError<E>("Tag")(...)、Layer.provideMerge、Effect.fn("Service.method") 等写法;用 @effect/platform 构建 HTTP 服务端/客户端,用 @effect/cli 构建 CLI,用 @effect/rpc 构建 RPC,用 @effect/sql 访问 SQL,用 @effect/vitest 编写测试,用 @effect/opentelemetry 接入 OTel;用 @effect-atom/atom-react 构建 React 前端;以及将 Promise / fp-ts / neverthrow / RxJS 代码迁移到 Effect,或采用渐进式/可移植工具模式。
不适用:Effect-TS v4 或 v4 beta(严格仅限 v3,v4 语法如 ServiceMap.Service、Schema.TaggedErrorClass、裸 Effect.catch、Effect.forkChild、Effect.forkDetach、Schema.makeUnsafe、Result 模块均被禁止);不计划采用 Effect 的 fp-ts、neverthrow 或 RxJS 代码库(仅迁移文档适用);不含 Effect 的普通 TypeScript,或其他函数式生态(cats、ZIO)。
硬性规则(编码前必读):不要从 @effect/schema 导入(自 3.10 起已弃用),改用 import { Schema } from "effect";不要使用 v4 语法;不要在 Effect.gen 内 throw(会变成 defect),应使用 return yield* new TaggedError({...}) 或 Effect.fail(...);不要在 Effect.gen 内写 yield fx(缺少 ),必须 yield fx;不要在库、服务或中间件代码中调用 Effect.runPromise / Effect.runSync,仅在程序边缘调用;对超过 5 个元素的列表调用 Effect.all / Effect.forEach / Stream.mapEffect 时必须带 { concurrency: N };不要用 try / finally 做清理(会绕过中断),应使用 Effect.acquireRelease 或 Effect.ensuring;领域类型中不要放 null / undefined,使用 Option<T>;不要用 console.log,使用 Effect.log / logInfo / logError;不要直接读 process.env,使用 Config.string("X") / Config.redacted("X");不要用 Option.getOrThrow,使用 Option.match;不要用 as never / as any / as unknown 压制 Effect 类型错误;能用 catchTag / catchTags 保留类型收窄时不要用 catchAll;不要发明泛化错误名(NotFoundError、Error),使用具体 tagged error(如 UserNotFoundError);不要在 provide 处内联调用参数化 Layer 构造器,应存为模块级常量以便记忆化。
默认立场:业务服务默认用 Effect.Service 而非 Context.Tag(Context.Tag 用于多实现库和运行时注入的基础设施,如 worker 绑定、KV);默认用 Schema.TaggedError 而非 Data.TaggedError(前者可跨 RPC / HTTP 序列化,并可与 HttpApiSchema.annotations({ status: 404 }) 集成);默认从 "effect" 导入 Schema;命名函数默认用 Effect.fn("Service.method") 以获得自动 span 追踪与堆栈;顺序/分支逻辑默认用 Effect.gen,线性变换默认用 pipe;超过 5 个元素的列表默认加 { concurrency: N };增量组合默认用 Layer.provideMerge 而非 Layer.provide,独立 Layer 的扁平组合用 Layer.mergeAll;入口点默认用 NodeRuntime.runMain(优雅处理 SIGINT / SIGTERM),非 Effect 框架集成(Hono、Express、Next.js 路由处理器)用 ManagedRuntime;资源生命周期默认用 acquireRelease;在 Effect.gen 内抛出 tagged error 时默认用 return yield* 以便 TypeScript 收窄控制流。
常见症状与修复:出现 Missing 'X' in the expected Effect context 或 Effect<A, E, X> 不可赋值给 Effect<A, E, never>,通常是混淆了 Layer.provide 与 Layer.provideMerge;Effect.cachedWithTTL is not a function 或意外双重 yield,是因为 API 返回 Effect<Effect<A,E,R>> 而 yield 了两次;SubscriptionRef.unsafeMake is not a function,应改用 SubscriptionRef.make(initial);AI 幻觉出不存在的 API,需对照反模式文档核查;Effect 意外解析为 null,是 Effect.promise 把错误吞成 defect,应改用 Effect.tryPromise({ try, catch });测试用 mock 通过但生产失败,应把 vi.mock 换成 Layer.succeed(Service, mockImpl);Stream 挂起或程序不结束,是无限流缺少 take(N) / runHead;大 Effect.all 出现 OOM,是无界并行,需加 { concurrency: 10 };Ctrl-C 时 finalizer 不执行,是用了 try / finally 或 Effect.runPromise 而非 acquireRelease / NodeRuntime.runMain;OTel 无日志或追踪,是漏了 NodeSdk.layer 和 OtlpTracer.layer;header 返回 404,是 HttpApiEndpoint.setHeaders 的 header key 必须小写;Cannot find module '@effect/schema',是包已弃用,应改为从 "effect" 导入 Schema。
工作流:按当前任务只加载所需参考文件,分为核心(Effect 类型、创建、运行、组合子)、错误处理(类型化 tagged error)、服务与 Layer、Schema、数据类型、模式匹配、并发、状态、资源管理、Streams、Queue / PubSub、缓存与批处理、调度、Config、可观测性等章节,每章对应一组 references 路径。
限制:本技能严格限定 Effect-TS v3,不覆盖 v4;不适用于不采用 Effect 的 fp-ts / neverthrow / RxJS 代码库;不含 Effect 的普通 TypeScript 与其他函数式生态不在范围内。关于收费、价格、平台支持等具体信息,资料中暂未提供。