TypeScript 早已不只是"带类型的 JavaScript"——它是当下 Agent、全栈与基础设施开发的事实主力语言。本站的 TypeScript Agent 开发(Mastra)系列与 LangChain 系列里,大量代码都在和异步 IO、外部 API 与不可靠网络打交道。写得多了就会发现,async/await 单看很顺手,组合起来却处处漏风。
Effect 是 TypeScript 生态里最有代表性的函数式效应系统(functional effect system)。它不换语言、不换运行时,只用类型系统加一个运行时,把错误、依赖、并发这些"最难写对的部分"变成可组合的值。本文从 async/await 的痛点出发,依次讲清 Effect 的心智模型、gen 语法、类型化错误、结构化并发与 Layer 依赖注入,最后给一张"何时值得引入"的决策表。
1、原生 async 的痛点
先看一段再普通不过的代码:
async function getUser(id: string): Promise<User> {
const row = await db.query("SELECT * FROM user WHERE id = ?", id);
const cached = await redis.get(`user:${id}`);
return JSON.parse(row.profile); // 三步都可能抛错
}
try {
const user = await getUser("42");
} catch (e) {
// e 是 unknown:三种错误在这里汇成一锅粥
throw new Error(`获取用户失败: ${String(e)}`); // 类型信息到此为止
}
问题不在于"写不出正确代码",而在于类型系统全程旁观。签名 Promise<User> 只承诺成功形态,失败形态完全不在场:调用方不知道会抛什么、不知道哪些错误已被上层处理,catch 里拿到的是 unknown,只能逐层包装成新错误,原始信息不断磨损。
第二个痛点是取消。Node.js 的 AbortSignal 需要你手工把信号一层层传进每个 IO 调用,漏传一处,超时后的请求就变成无人认领的悬挂 Promise。并发编排同样繁琐:Promise.all 一旦短路,已启动的任务并不会被取消;想要"任一成功即返回、其余自动清理",得靠 any、allSettled 或第三方库拼装。
错误信息同样会被吞掉。Promise.all 只抛出第一个拒绝的原因,其余子任务的失败从此无人知晓;线上排查时,你常常只拿到一条日志,却还原不出当时的全貌。换句话说,原生并发既不保证清理,也不保证可观测,这两件事都得自己搭基建。
这三件事——错误类型丢失、取消传播、并发编排——本质是同一个问题:Promise 是"已经开始的计算"。它无法被检查、无法预先组合,只能被动等待。Effect 的全部设计都从这一点出发。
2、Effect 心智模型
官方 README 对 Effect 的自我描述是:
Effect is a library for building robust, maintainable, type-safe, and production grade applications in TypeScript.
一句话概括:Effect 值是对计算的描述,而不是计算本身。Effect.tryPromise(...) 返回一个值,此刻什么都没发生;你可以检查它的类型、变换它、组合它,直到交给运行入口(如 Effect.runPromise)才真正执行。这与"Promise 一创建就开跑"是根本区别——描述先于执行,所以一切皆可组合。
类型上,每个 Effect 都带三个参数:Effect<Success, Error, Requirements>。各参数含义如下:
| 参数 | 含义 | 为 never 时 |
|---|---|---|
Success |
成功时产出的值类型 | 计算不可能成功 |
Error |
可能失败的全部类型,联合类型 | 计算不可能失败 |
Requirements |
执行所需的服务上下文 | 无外部依赖,可直接运行 |
这个模型可以用一张图概括:描述层负责组合与类型检查,运行时负责调度、并发与中断。
图的关键在左右两侧的分工:左侧一切都是类型层面的普通值,检查在编译期完成;右侧的运行时统一处理并发、取消、重试这些运行期难题。写 Effect 代码时,你大部分时间活在左侧。
描述与执行分离还带来一个隐藏红利:同一段程序可以在不同入口换不同的运行配置——生产环境挂上重试与超时策略,测试环境用 TestClock 冻结时间、瞬间验证退避逻辑,程序本身一行不改。时间在 Effect 里也是可以被注入的依赖,这是 async 代码想都不敢想的能力。
顺带说工程现状:Effect 4.x 是当前长期支持版本(写作时 npm 最新为 4.1.2),4.0 重写了运行时并显著缩小了打包体积,GitHub 仓库星标约 1.75 万,2026 年 11 月仍在高频发布。官方生态提供面向 Anthropic、OpenAI、Cloudflare 等平台的集成包,甚至打出了 "TypeScript for the AI era" 的口号——AI 应用正是它重点瞄准的场景。
3、gen 语法走读
有了"描述而非执行"的模型,下一个问题是怎么写起来不像天书。答案是 Effect.gen:它借用 JavaScript 生成器语法,长相几乎和 async/await 一样。以调用大模型生成摘要为例:
import { Data, Effect } from "effect";
class ApiError extends Data.TaggedError("ApiError")<{ status: number }> {}
const summarize = (text: string): Effect<string, ApiError, never> =>
Effect.gen(function* () {
const res = yield* Effect.tryPromise({
try: () => callModel(text), // 接住现有 Promise
catch: (cause) => new ApiError({ status: 502 }), // 错误显式映射
});
return res.choices[0].content; // 返回值即成功分支
});
// 惰性:不调运行入口,上面什么都不会发生
await Effect.runPromise(summarize(longText));
逐行走读:
function*声明生成器,yield*就相当于这里的await;- 每个
yield*的错误类型与依赖类型自动向上传播,整段的联合类型由编译器推导; - 普通返回值自动成为成功分支,最终签名
Effect<string, ApiError, never>就是文档。
唯一的纪律:yield* 右边必须是 Effect,不能是裸 Promise。要接 Promise 就用 Effect.tryPromise 包一层并显式映射错误——这步"麻烦"恰恰是把未知错误挡在门外的关卡。
顺带一提,Effect 同时支持 pipe 风格的链式组合:source.pipe(Effect.map(f), Effect.flatMap(g))。函数式老手偏爱它的 point-free 风格,新手则从 gen 入手门槛最低;两种风格可以混用,团队内部统一即可。
4、失败是类型的一等公民
回到第 1 节的 getUser,用 Effect 重写后,失败形态直接进签名,对比非常直观。先看传统版的读取配置:
// 传统:签名里没有任何失败信息
async function readConfig(): Promise<Config> {
const text = await fs.readFile("app.json", "utf8"); // 可能抛 IO 错误
return JSON.parse(text); // 可能抛解析错误
}
调用方只能 catch (e: unknown) 然后靠猜。Effect 版则把两种失败都写成类型,消费端按需恢复:
class FsError extends Data.TaggedError("FsError")<{ path: string }> {}
class ParseError extends Data.TaggedError("ParseError")<{ cause: unknown }> {}
const readConfig: Effect<Config, FsError | ParseError, never> =
Effect.gen(function* () {
const text = yield* readText("app.json");
return yield* parseJson<Config>(text); // 错误自动并入联合
});
// 按 tag 精确恢复,其余错误继续向上传播
const withDefault = readConfig.pipe(
Effect.catchTag("ParseError", () => Effect.succeed(DEFAULT)),
);
行为差异在于:传统版的错误处理是约定俗成的运行时行为,Effect 版的错误处理是编译期可验证的类型事实。Data.TaggedError 给每个错误一个 _tag 字面量,catchTag 靠它做精确分支,比 instanceof 在序列化与跨包场景下可靠得多;未恢复的错误会一路传到运行入口,无法凭空消失。
这套"错误即值"的模型还有个隐性收益:重试、超时、降级都是对 Effect 值的组合变换。Effect.retry 配上指数退避策略、Effect.timeout 加上截止时间,都只是在 pipe 里追加一步,策略与业务逻辑彻底解耦,不需要 try/catch 嵌套三层再手工计数。
5、结构化并发与取消
并发是 Effect 运行时最能打的场景,核心 API 三个,要点如下:
Effect.all:并发执行一组 Effect,任一失败立即中断其余Effect.race:竞速执行,先完成者胜,败者自动中断Effect.fork:派生子 fiber,生命周期绑定父作用域
并发示例如下:
// 三个请求并发聚合报告;任一失败,其余立刻取消
const report = Effect.all(
[fetchUser(id), fetchOrders(id), fetchCredits(id)],
{ concurrency: "unbounded" }, // 显式开启并发
);
// 主库慢了就切备库:先返回者生效,另一个被中断
const user = Effect.race(queryPrimary(id), queryReplica(id));
对比原生方案:Promise.all 短路后其余请求照跑不误;Promise.race 的输家继续占着连接;想要"全都要、失败即停、赢家通吃"的语义,原生只能靠 AbortController 手工编排,而 Effect 把它做成了运行时默认行为。fiber 是比 Promise 更完整的并发单元——有状态、可中断、可 join:fork 出的子 fiber 能通过 Fiber.join 回收结果,也能被主动 interrupt;中断信号沿父子关系级联传播,"父任务取消、子任务必然清理"不需要任何手工保证。AI Agent 里"多工具并行调用、超时熔断"这类需求正好对口。
6、Layer 依赖注入
前面签名里的第三个参数 Requirements 一直没展开,它由 Layer 体系消费。思路是:服务用 Context.GenericTag 声明"是什么",用 Layer 提供"怎么做",业务代码只声明"我要什么"。小例:
import { Context, Effect, Layer } from "effect";
interface Logger {
log: (msg: string) => Effect<void>;
}
const Logger = Context.GenericTag<Logger>("Logger");
// 只声明依赖 Logger,不关心实现
const greet = (name: string): Effect<void, never, Logger> =>
Effect.gen(function* () {
const logger = yield* Logger; // 从环境取服务
yield* logger.log(`hello ${name}`);
});
// 生产与测试实现,一行切换
const prodLayer = Layer.succeed(Logger, {
log: (m) => Effect.sync(() => console.log(m)),
});
const testLayer = Layer.succeed(Logger, { log: () => Effect.void });
const program = greet("Quibbler").pipe(Effect.provide(prodLayer));
await Effect.runPromise(program); // 依赖已配齐,可以运行
Effect.provide 把 Layer 注入程序,Requirements 参数随之收窄为 never——依赖没配齐,程序就运行不了,缺服务的错误在编译期报出,而不是运行时的 undefined is not a function。Layer 自身也可组合:Layer.merge、Layer.provide 能把十几个服务的装配图拼成一个总 Layer,应用入口常常只剩一行 runPromise。测试时把日志、数据库服务换成内存实现,业务代码一行不动。
7、何时值得引入
Effect 不是免费午餐。它的词汇表不小,fiber、layer、schema 都是新名词;团队头一两个月的开发速度大概率下降;小项目里三参数签名反而是负担。2026 年它的社区处在"基础设施公司先吃螃蟹"的阶段:官网案例里有 14.ai 用它构建 AI 客服系统、Langton 团队大规模迁移存量代码,运营方 Effectful 还拿到了 Amplify Partners 的投资,4.0 的发布记录也显示迭代极快,但主流前端业务团队用它仍是少数派。
不同场景的引入建议如下:
| 场景特征 | 引入建议 | 理由 |
|---|---|---|
| 脚本与单页小工具 | 不建议 | 学习成本远超收益,async 足够 |
| 普通 CRUD 服务 | 谨慎 | 收益有限,除非错误处理已是主要 bug 来源 |
| 多外部依赖编排 | 推荐 | 重试、超时、熔断的组合管道直接受益 |
| AI Agent 后端 | 推荐 | 工具并发调用、超时熔断、可观测性是刚需 |
| 底层 SDK 与框架 | 推荐 | 强类型边界能保护下游使用者 |
一句话忠告:先在一个非核心模块跑三个月,让团队把 gen、错误、Layer 三件事吃透,再决定是否铺开。
所谓学习成本,一半是新 API,另一半是心智转变——从"调用即执行"转向"先描述、后运行"。前者靠文档与练习,后者只能靠写;不过一旦适应,回头看裸 async 代码反而会觉得少了点什么。迁移路径上还有个务实选择:Effect 可以与现有 async 代码共存,Effect.tryPromise 包一层就能把旧函数接进新管道,不必推倒重来。
8、总结
回看全文的四个支点:async/await 的组合性问题源于 Promise 不可描述、不可检查;Effect 用 Effect<Success, Error, Requirements> 把计算变成值,描述与执行分离;gen 语法让这种风格写得像 async/await 一样顺;错误、并发、依赖三个难题分别由 tagged error、结构化并发与 Layer 体系兜底。
想上手的话,给三个循序渐进的小练习:
- 把项目里"读文件、解析 JSON、兜底默认值"的函数改写成 Effect,体会错误进签名;
- 用
Effect.all与Effect.race实现一次主备 API 竞速,观察败者是否真被中断; - 给一个函数声明
Logger依赖,写生产与测试两个 Layer,验证编译期缺依赖报错。
对于在 TypeScript 里构建 Agent 或多依赖后端服务的团队,建议认真评估 Effect——它把"最难写对的部分"交给类型系统和运行时,换来的是可组合、可测试、失败可见的代码。入门从官方文档的入门篇开始即可,npm 包页可跟踪版本动态。

