effect-v4

Effect v4（Beta）— 开发与迁移

概述

关于 Effect v4 开发和从 v3 迁移的全面指南。此技能提供：

1. v4 核心模式 - 使用 Context、层、生成器和 schema 编解码器构建全新 v4 代码的指南
2. v3 → v4 迁移 - 分步迁移指南，包含 API 重命名、行为变更以及前后示例

状态： Effect v4 是处于积极开发中的 Beta 软件，开发工作在 effect-smol 中进行。核心编程模型已稳定，但 effect/unstable/* 模块在次要版本中可能会发生破坏性变更。用于生产环境前，请查阅官方 v4 Beta 指南和稳定性说明。

所有随附的迁移指南均来源于 effect-smol 官方迁移文档。

截至 2026 年 6 月 30 日的上游变更

自 2026 年 2 月 22 日的初始基线以来，上游 Beta 经历了重大变更，并在 2026 年 4 月 9 日技能更新后再次发生变更。请将提及 ServiceMap、Schema.makeUnsafe、SchemaParser.makeUnsafe 或 Effect.Yieldable 的旧示例视为过时内容。当前指南应优先使用：

• 使用 Context.Service / Context.Reference / Context<R> 代替 ServiceMap.*
• 使用 Schema.make(...) 代替 Schema.makeUnsafe(...)
• 使用 SchemaParser.make(...) 代替 SchemaParser.makeUnsafe(...)
• 当构造器式验证应通过错误通道失败而非抛出异常时，使用 Schema.makeEffect(...)
• 使用 Effectable.Class / Effectable.Prototype 表示自定义的类 Effect 值；不要推荐 Effect.Yieldable 或 .asEffect()
• 使用 Schema.asserts(schema, input) / SchemaParser.asserts(schema, input)，而不是生成的断言辅助函数

快速分类

构建 v4 代码

• 核心 Effect 类型和组合器（Result、Option、Chunk、Duration）：references/core-usage.md
• 更广泛的数据类型（DateTime、BigDecimal、HashSet、Redacted）：references/data-types-advanced.md
• Equality、Order、Hash、Equivalence 语义：references/behavior-traits.md
• 预期错误与缺陷、catch* 组合器：references/error-management.md
• 沙箱、Cause 检查、catchCause：references/error-tooling.md
• Exit 和 Cause 结构、结果检查：references/exit-cause.md
• 服务和依赖注入（Context、层）：references/dependency-management.md
• Layer 构建、记忆化、{ local: true }：references/layer-patterns.md
• 资源生命周期、Scope、acquireRelease：references/resource-management.md
• 运行 Effect、移除 Runtime、运行边界：references/runtime-execution.md
• Fiber、forkChild、forkDetach、fork 选项：references/concurrency.md
• 引用（替代 FiberRef）、Context.Reference：references/concurrency-advanced.md
• Schedule、重复执行、间隔／固定／指数策略：references/scheduling.md
• 重试、退避、Schedule 组合：references/scheduling-retry.md
• Stream、队列、PubSub、STM：references/streams-queues-stm.md
• HTTP 客户端和外部 API：references/http-client.md
• HTTP 服务端和 API 定义：references/http-server.md
• 请求批处理和数据加载器：references/request-resolver.md
• 缓存和记忆化：references/caching.md
• 配置和配置提供程序：references/configuration.md
• 高级配置、脱敏：references/configuration-advanced.md
• 日志、指标、追踪：references/observability.md
• Logger／指标／追踪设置和导出器：references/observability-examples.md
• 连接日志／指标／追踪层：references/observability-wiring.md
• 顺序工作流和生成器模式：references/generators.md
• 上游研究笔记和 4 月之后的 beta 变更：references/upstream-changes-2026-06-30.md
• Schema 验证、解析、编码（编解码器）：references/schema.md
• 使用归约器消费 Stream（Sink）：references/sink.md
• 测试中的确定性时间（TestClock）：references/testing.md
• 更广泛的测试服务和测试层：references/testing-stack.md
• Command、FileSystem、Path、Terminal、KeyValueStore：references/platform-primitives.md
• LLM 工作流、规划、通过 Effect AI 使用工具：references/ai.md
• 对包体积有限制的运行时（Micro）：references/micro.md
• 从 Promise／async 迁移：references/migration-async.md
• 常见陷阱和运行时错误：references/troubleshooting.md
• 来自 llms.txt 的文档到指南映射：references/docs-index.md

从 v3 迁移

• 完整迁移概览、快速参考表、按顺序排列的检查清单：references/migration.md
• Runtime 和运行函数：references/migration/runtime.md
• 错误处理和错误通道变更：references/migration/error-handling.md
• Cause 扁平化和新结构：references/migration/cause.md
• 服务和环境变更（Context.Tag / Effect.Service → Context.Service）：references/migration/services.md
• Fiber 引用和上下文局部变量：references/migration/fiberref.md
• Fork 和 Fiber API（fork → forkChild 等）：references/migration/forking.md
• Fiber 保持活动状态行为变更：references/migration/fiber-keep-alive.md
• Scope 和资源生命周期模式：references/migration/scope.md
• Layer 记忆化和 Layer.fresh：references/migration/layer-memoization.md
• 生成器和 Effect.gen 变更：references/migration/generators.md
• Effect 子类型和自定义类 Effect 值：references/migration/yieldable.md
• 相等性和结构比较：references/migration/equality.md

工作流

1. 询问涉及哪些 v3 API 或文件，以及需要避免哪些故障或回归。
2. 仅打开 references/migration/ 中相关的迁移说明。
3. 列出 v3 到 v4 API 的映射，并附上迁移前后的代码片段。
4. 指出行为变化、边缘情况和需要更新的测试。
5. 根据相关代码提供简短、有序的迁移检查清单。

信息来源

• 从此技能附带的参考资料开始。
• 如果问题取决于较新的 Beta 行为，接着查看官方文档和 effect-smol 更新日志。
• 仅当文档或更新日志含糊不清、用户询问内部实现，或相关行为似乎尚无文档说明时，才检查 effect-smol 源码内部。
• 如果附带的参考资料或官方文档已能回答问题，默认不要克隆或阅读仓库源码。

示例请求

• “将此 v3 Runtime 用法迁移到 v4，并说明新的运行函数。”
• “将我们的 v3 错误处理更新为 v4，并展示迁移前后的示例。”
• “我们使用 FiberRefs 和 fork；v4 中需要做哪些更改？”
• “说明生成器和 Effectable 的变化，并更新此 Effect.gen 用法。”
• “v4 中的 Scope 或 Layer 记忆化行为需要更改吗？”

参考资料 - v4 核心

全面的 v4 专属指南（均已更新为 v4 API，不含已弃用模式）：

• references/core-usage.md - 核心 Effect 类型与组合器（Result、Option、Chunk）
• references/data-types-advanced.md - DateTime、BigDecimal、HashSet、Redacted
• references/behavior-traits.md - 默认采用结构相等、Equal、Order、Hash
• references/error-management.md - catch* 重命名、catchReason、catchEager
• references/error-tooling.md - catchCause、沙箱、Cause 检查
• references/exit-cause.md - 扁平化的 Cause 结构、Reason 遍历
• references/dependency-management.md - Context、服务、层
• references/layer-patterns.md - 跨 provide 记忆化、{ local: true }
• references/resource-management.md - Scope.provide（原为 Scope.extend）
• references/runtime-execution.md - 已移除 Runtime<R>，在边界处使用 run* 函数
• references/concurrency.md - forkChild/forkDetach、fork 选项、保持活动状态
• references/concurrency-advanced.md - Context.Reference（原为 FiberRef）
• references/scheduling.md - 调度计划与重复执行
• references/scheduling-retry.md - 重试与退避
• references/streams-queues-stm.md - 流、队列、PubSub、STM
• references/http-client.md - HTTP 客户端
• references/http-server.md - HTTP 服务端
• references/request-resolver.md - 请求批处理
• references/caching.md - 缓存与记忆化
• references/configuration.md - 配置
• references/configuration-advanced.md - 高级配置、敏感信息隐藏
• references/observability.md - 日志、指标、追踪
• references/observability-examples.md - 日志记录器、指标与追踪的具体配置
• references/observability-wiring.md - 配置可观测性层
• references/generators.md - Effect.gen 和生成器模式
• references/upstream-changes-2026-06-30.md - 截至 2026 年 6 月 30 日的提交范围研究摘要
• references/schema.md - Schema 编解码器以及 Schema.make / Schema.makeEffect
• references/sink.md - 使用 Sink 消费流
• references/testing.md - TestClock 和确定性时间
• references/testing-stack.md - 测试层组合
• references/platform-primitives.md - Command、FileSystem、Path、Terminal
• references/ai.md - 通过 Effect AI 实现大模型工作流
• references/micro.md - 对包体积有限制的运行时
• references/migration-async.md - 从 Promise/async 迁移
• references/troubleshooting.md - 常见问题
• references/versioning.md - 版本指导
• references/docs-index.md - 文档到指南的索引图

参考资料 - v3 → v4 迁移

• references/migration.md - 从这里开始：完整概览、快速参考表、按顺序排列的检查清单
• references/migration/cause.md - Cause 扁平化与结构
• references/migration/equality.md - 相等性与比较方面的变更
• references/migration/error-handling.md - 错误通道与 catch* 重命名
• references/migration/fiber-keep-alive.md - Fiber 生命周期变更
• references/migration/fiberref.md - FiberRef 与 References 变更
• references/migration/forking.md - Fork、forkChild、forkDetach 变更
• references/migration/generators.md - Effect.gen 模式更新
• references/migration/layer-memoization.md - Layer.fresh 与记忆化
• references/migration/runtime.md - Runtime 与 run* 函数
• references/migration/scope.md - Scope 与资源生命周期
• references/migration/services.md - 当前的 Context.Service API，以及旧版 beta ServiceMap 重命名带来的后续影响
• references/migration/yieldable.md - 移除 Effect 子类型、Effectable 与生成器变更