Effect 教程：由浅入深

从 async/await 的三个盲区出发，逐步讲清类型、错误、依赖、并发、资源与工程化。每章只引入一类新概念。（共 23 篇）

第 1 章

为什么需要 Effect：async/await 看不见的三件事

教程第 1 章。从一个普通的 async 函数出发，说明签名里看不见的三件事：会怎样失败、依赖了什么、能不能被取消，以及 Effect 如何把它们写进类型。

第 2 章

第 3 章

第 4 章

第 5 章

错误是类型：failure 与 defect、TaggedError、catchTag

把错误写进 Effect 的 E 参数：区分可预期的失败（failure）与不可预期的缺陷（defect），用 TaggedError 定义领域错误，再用 catchTag 精确恢复并让类型随之收窄。

第 6 章

第 7 章

第 8 章

用 Schema 建模：transform、brand 与判别联合

从校验走向建模：用 transform 连接外部表示与内部类型，用 brand 区分形状相同的值，用判别联合让非法状态无法表示，把领域规则写进类型。

第 9 章

服务：接口与实现分离，Context.Service

Effect 教程第 9 章：为什么依赖应该写进类型而不是藏在 import 里，Context.Service 如何把「能力的接口」与「能力的实现」拆开，R 参数怎样自动汇总依赖，以及服务设计里常见的几种误用。

第 10 章

Layer：构建依赖图、生命周期与组合

Effect 教程第 10 章：服务的实现从哪里来。讲清 Layer 的三个参数、provide、provideMerge 与 mergeAll 的区别，资源如何建立与释放，以及依赖图只构建一次的含义。

第 11 章

配置与密钥：Config、Redacted 与环境差异

Effect 教程第 11 章：为什么不该直接读 process.env。讲 Config 是描述、Layer 构造时 fail-fast、withDefault 的边界、Redacted 防泄漏与 ConfigProvider 切换环境。

第 12 章

测试：替身 Layer、可控的时间

Effect 教程第 12 章：依赖用 Layer 注入之后测试怎么变简单。讲替身 Layer、用 Effect.flip 断言类型化失败、TestClock 让超时与重试不再真等，以及共享 Layer 的取舍。

第 13 章

Fiber 心智模型：结构化并发

用 async/await 的视角理解 fiber：它是什么、为什么子任务必须属于父任务，以及 forkChild、join、interrupt 各自表达的语义。讲清「中断不是失败」与结构化并发的价值。

第 14 章

并发组合子：all、forEach、race，并发度与失败传播

讲清 Effect.all、Effect.forEach、Effect.race 的语义：默认顺序执行、concurrency 选项如何限制并发度、一个任务失败时其余任务会怎样，以及如何收集全部结果而不是遇错即停。

第 15 章

中断与资源安全：Scope、acquireRelease、finalizer

讲解为什么 try/finally 在异步与中断场景下不够用，以及 Effect 如何用 Scope、acquireRelease 与 finalizer 保证资源一定释放：获取与释放成对、后进先出、中断时同样生效。

第 16 章

时间与重试：Schedule、退避与超时

外部调用既会慢也会偶发失败。本章讲清 Schedule 为什么是一个可组合的策略值，退避、上限与抖动怎么拼，哪些失败值得重试，以及 timeout 和 retry 谁包着谁。

第 17 章

流：Stream 与背压，以及什么时候不该用

数据不是一次到齐，而是一批批流过来。本章讲 Stream 是什么、惰性拉取与背压怎样让内存保持有界，常用的构造、变换与消费方式，以及哪些场景用数组或 forEach 更合适。

第 18 章

共享状态：Ref、Queue、PubSub、Semaphore 怎么选

多个 fiber 要共享数据、互相传递工作或限制并发时，该用哪个原语？本章按「要解决的问题」而不是按 API 来分类：Ref 存值、Queue 派活、PubSub 广播、Semaphore 限流，并讲清各自的边界。

第 19 章

运行时边界：ManagedRuntime、与框架接合、Workers

Effect 程序只是描述，总得有人在某个地方真正运行它。本章讲清运行只发生在边缘的含义、为什么长驻进程要构建一个 ManagedRuntime，以及接入 Web 框架和 Cloudflare Workers 时边界该画在哪里。

第 20 章

可观测性：日志、span、指标，先想清楚观测什么

Effect 把日志、tracing 和指标都做成内置能力，函数加一层包装就能产生 span。但工具不会替你决定该看什么。本章先讲三种信号各自回答什么问题，再讲怎么在代码里挂上去、怎么导出，以及常见的滥用方式。