# Effect-TS 专家指南 Effect-TS 是一个函数式 TypeScript 库，提供类型化效果、结构化并发和强大的运行时。该技能涵盖了正确的使用模式，并解决了 LLM 生成的内容中的常见误解。 ## 快速参考从“effect”导入{ Effect、Layer、Context、Fiber、Schedule、Cache、Scope }；从“@effect/schema”导入{Schema，JSONSchema}； **核心类型签名：** 效果<成功、错误、要求> // ↑ ↑ ↑ // | | └── 依赖关系（通过层提供） // | └── 预期错误（已输入，必须处理） // └── 成功值 ** ** ## 常见的误解 **LLM 输出通常包含不正确的 API。** 使用此表来更正它们：错误（常见于AI输出）|正确 ---|--- `Effect.cachedWithTTL(...)` | `Cache.make({ timeToLive: 持续时间 })` `Effect.cachedInvalidateWithTTL(...)` | `cache.invalidate(key)` / `cache.invalidateAll()` `Effect.match(...)` | `Effect.either` \+ `Either.match` 或 `Effect.catchTag` “线程本地存储”|通过“FiberRef”的“光纤本地存储” JSON 架构草案 2020 年 12 月 | `@effect/schema` 生成 **Draft-07** 纤维被“取消” |纤维被“终止”或“中断” 所有队列都有背压|仅**有界**队列；滑动/掉落不 `--only=生产` | `--omit=dev` (npm 7+) ** ** ## 错误处理：两种错误类型效果区分： 1. **预期错误（失败）** \- 在`E`通道中输入，必须处理 2. **意外错误（缺陷）** \- 运行时错误，已捕获但未键入 // 预期错误 - 输入 const fetchUser = (id: string): Effect.Effect => ... // 处理预期的错误常量处理 = 管道( 获取用户（“123”）， Effect.catchTag("UserNotFoundError", (e) => Effect.succeed(defaultUser)), Effect.catchTag("NetworkError", (e) => Effect.retry(schedule)) ）； // 意外错误（缺陷）- 由运行时捕获 Effect.catchAllDefect(程序, (缺陷) => Console.error("意外错误", 缺陷) ）； ** ** ## 纤维和取消（对于 MCP 至关重要）光纤是具有**本机中断**的轻量级虚拟线程： // 分叉一个纤程 const Fiber = 产量* Effect.fork(longRunningTask); // 中断它（例如，当 MCP 客户端断开连接时）产量* Fiber.interrupt(optical); // 结构化并发：子纤维与父纤维自动终止 const 父 = Effect.gen(function* () { 产量* Effect.fork(backgroundTask); // 当父进程结束时自动中断产量*主任务； }); // 守护进程纤维比其父进程寿命更长产量* Effect.forkDaemon(longLivedBackgroundTask); ** ** ## 并发原语 ### Effect.race - 先胜后败 // 先成功者获胜；其他自动中断 const 结果 = 产量* Effect.race( 从缓存中获取，从数据库获取）； ### Effect.all 与并发控制 // 处理 50 个文档，最多 5 个并发 const 结果 = 产量* Effect.all(documents.map(processDoc), { concurrency: 5 // 不是“工作池” - 限制并发任务 }); ### 队列类型 // 有界 - 应用背压（报价满时暂停） const 有界 = 产量* Queue.bounded(100); // Dropping - 满时丢弃新项目（无背压） const 丢弃 = 产量* Queue.dropping(100); // 滑动 - 满时丢弃最旧的项目（无背压）常量滑动 = 产量* Queue.sliding(100); ** ** ## 依赖注入层层构建服务而不泄漏依赖关系： // 定义一个服务类数据库扩展 Context.Tag("数据库")< 数据库， { 查询：(sql: 字符串) => Effect.Effect<结果> } >() {} // 创建层（构建时处理的依赖关系） const DatabaseLive = Layer.effect( 数据库， Effect.gen(函数* () { const config = 产量* 配置； // 这里注入依赖返回{ 查询： (sql) => Effect.tryPromise(() => runQuery(sql, config)) }; }) ）； // 提供给程序 const runnable = program.pipe(Effect.provide(DatabaseLive)); // 用于测试 - 交换实现 const DatabaseTest = Layer.succeed(数据库, { 查询：() => Effect.succeed(mockResult) }); ** ** ## 资源管理 ### Effect.ensuring - 始终运行终结器常量程序 = 管道( Effect.tryPromise(() => openConnection()), Effect.ensuring(Console.log("Cleanup")) // 在成功、失败或中断时运行）； ### acquireUseRelease 模式 const withConnection = Effect.acquireUseRelease( Effect.tryPromise(() => db.connect()), // 获取 (conn) => Effect.tryPromise(() => conn.query("SELECT *")), // 使用 (conn) => Effect.promise(() => conn.close()) // 释放（始终运行））； ### 资源生命周期的范围效果.范围( Effect.gen(函数* () { const 文件 = 产量* openFile("data.txt"); // 已获取 const 数据 = 产量* file.read(); 返回数据； }) // 当范围关闭时文件自动释放）； ** ** ## 缓存 **没有`Effect.cachedWithTTL`。**使用Cache模块：从“效果”导入{缓存}； const 缓存 = 产量* Cache.make({ 容量：100，生存时间：持续时间.分钟（5），查找：（键：字符串）=> fetchExpectiveData（键） }); // 使用缓存 const value =ield*cache.get(“my-key”); // 无效产量*cache.invalidate(“我的密钥”); 产量*缓存.invalidateAll(); ** ** ## 按计划重试从“效果”导入{时间表}； // 以指数退避重试 3 次 const policy = Schedule.exponential("100 millis").pipe( Schedule.intersect(Schedule.recurs(3)) ）； const 健壮 = Effect.retry(unstableOperation, 策略); // 重试直到满足条件 const 直到成功 = Effect.retry(操作, { 直到：（err）=> err.code ===“RATE_LIMITED” }); ** ** ## 架构和 JSON 架构 `@effect/schema` 生成 **JSON Schema Draft-07**（不是 2020-12）：从“@effect/schema”导入{Schema，JSONSchema}； const 用户 = Schema.Struct({ id：架构.字符串，年龄：Schema.Number.pipe(Schema.positive()) }); // 生成 JSON 架构 (Draft-07) const jsonSchema = JSONSchema.make(用户); // { "$schema": "http://json-schema.org/draft-07/schema#", ... } // 解码（解析） const user = Schema.decodeUnknownSync(User)(rawData); // 编码 const json = Schema.encodeSync(User)(用户); ** ** ## 可观测性和 OpenTelemetry Effect 具有原生 OpenTelemetry 集成：从“@effect/opentelemetry”导入{ NodeSdk }；从“@opentelemetry/exporter-trace-otlp-http”导入{ OTLPTraceExporter }； // 添加跟踪以实现任何效果 const 追踪 = Effect.withSpan("processRequest")(myEffect); // 记录上下文 Yield* Effect.log("正在处理请求"); 产量* Effect.annotateLogs("requestId", "abc-123"); // FiberRef 用于光纤本地上下文传播 const RequestId = FiberRef.unsafeMake(""); 产量* FiberRef.set(RequestId, "req-456"); ** ** ## 何时不使用效果场景 |推荐 ---|--- 简单的 MCP 工具（< 100 LOC）|使用 FastMCP 或 vanilla SDK 团队不熟悉FP |陡峭的学习曲线；考虑 NestJS 捆绑尺寸至关重要 |效果至少增加 15-25kb gzipped 现有的 NestJS/TypeORM 代码库 |与基于类别的 DI 阻抗不匹配 ** ** ## MCP 服务器模式 ### 带有类型错误的工具处理程序 const searchTool = Effect.gen(function* () { const args = 产量* parseArgs(输入); const db = 产量* 数据库； const 结果 = 产量* db.query(args.query); 返回格式结果（结果）； }).管道( Effect.catchTag("ParseError", () => Effect.fail({ code: -32602, message: "无效参数" }) ), Effect.catchTag("数据库错误", () => Effect.fail({ code: -32603, message: "内部错误" }) ））； ### 请求范围 // 每个 MCP 请求都有自己的范围 const handleRequest =（请求：MCPRequest）=> 效果.范围( Effect.gen(函数* () { // 这里获取的资源在请求完成时自动释放 const tempFile = 产量* createTempFile(); const 结果 = 产量* processRequest(请求, tempFile); 返回结果； }) ）； ** ** ## 资源 * [效果文档]() * [效果 GitHub]() * [@effect/schema JSON 架构]() * [@effect/opentelemetry]()

效应Ts

包含技能