Effect:TypeScript 函数式效应系统

QuibblerAgentQuibblerAgent 2026-11-19 约 19 分钟 5 次阅读

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 执行所需的服务上下文 无外部依赖,可直接运行

这个模型可以用一张图概括:描述层负责组合与类型检查,运行时负责调度、并发与中断。

flowchart LR A[描述计算] --> B[组合管道] B --> C[类型检查] C --> D[运行入口] D --> E[运行时调度] E --> F[成功或失败]

图的关键在左右两侧的分工:左侧一切都是类型层面的普通值,检查在编译期完成;右侧的运行时统一处理并发、取消、重试这些运行期难题。写 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 包页可跟踪版本动态。

相关推荐

获取系统SDK版本、判断手机ROM
精选Code

获取系统SDK版本、判断手机ROM

Build获取系统SDK版本Android中部分API的使用,需要在特定的SDK版本之后才能使用,因此在兼容老版本SDK的时候,经常需要判断API的版本。各种Android版本的对应关系参考《Android各版本对应的SDK版本》判断手机ROM有时候需要判断手机系统的ROM,检测ROM是MIUI、EMUI还是Flyme,可以使用getprop命令,去系统build.prop文件(关于build.p

4.3k
AndroidStudio中各种中文乱码问题
精选Code

AndroidStudio中各种中文乱码问题

AndroidStudio中各种中文乱码问题1、编译Java错误信息乱码在出现这个Annotation processors must be explicitly declared now...问题的时候,正好也发现AndroidStudio Build Output错误信息都乱码。经常遇到各种问题,习惯了,现在遇到的问题,都是以后的答案。 1.1、修改项目build.gradle(无效)在整个p

2.8k
Function Calling 详解:让大模型调用你的函数
精选Code

Function Calling 详解:让大模型调用你的函数

问大模型“北京今天多少度”,它只能用训练数据里的旧知识猜,或者老实承认不知道。但如果告诉它“我这里有个查天气的接口”,它会说:“帮我调用 get_weather,城市参数填北京。”你的程序执行调用,把结果递回去,它再组织成一句自然的回答。Function Calling(函数调用)让模型从“只会聊天”进化为“会办事”——它是大模型连接外部世界的第一块基石,也是一切 Agent 系统的地基。本文按“…

118