effect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Effect

Use current Effect v4 APIs and the production defaults in this skill. Established project conventions still take precedence unless the task is explicitly changing them.

使用本技能中的当前Effect v4 API和生产环境默认配置。除非任务明确要求更改，否则已确立的项目约定仍优先适用。

Source Rule

来源规则

Check these before guessing:

the nearest
```
AGENTS.md
```
and any project-local Effect practices doc
the project-pinned
```
effect
```
package source and version
current upstream Effect source when the installed package does not answer the question

在猜测之前，请先检查以下内容：

最近的
```
AGENTS.md
```
文件以及任何项目本地的Effect实践文档
项目固定版本的
```
effect
```
包源码和版本信息
当已安装的包无法解答问题时，查看当前上游的Effect源码

Branch Chooser

分支选择器

Read only the branch references that match the task.

Data models, schemas, brands, variants, optional keys, or decoders: read
```
references/SCHEMA.md
```
.
Services, module surfaces, layers, runtime wiring, errors,
```
Effect.fn
```
, or test services: read
```
references/SERVICES_LAYERS.md
```
.

Runtime config, env variables,

ConfigProvider

, or

layerConfig

: read

references/CONFIG.md

Retry, repeat, polling, backoff, jitter, rate-limit-aware policies, or pass loops: read
```
references/SCHEDULING.md
```
.
Memoization, per-key TTL caches, deduplicating concurrent lookups, or request batching: read
```
references/CACHING.md
```
.
Streams, event sources, async iterables, queues/pubsubs, pagination, backpressure, or stream consumers: read
```
references/STREAMS.md
```
.
Outgoing HTTP calls, Effect HttpClient, status handling, or HTTP rate limiting: read
```
references/HTTP_CLIENTS.md
```
.
Effect tests, time, sleeps, concurrency synchronization, or fakes: read
```
references/TESTING.md
```
.

If a task spans several branches, read all matching files before editing.

仅阅读与任务匹配的分支参考内容：

数据模型、模式、品牌、变体、可选键或解码器：阅读
```
references/SCHEMA.md
```
。
服务、模块接口、层、运行时连接、错误、
```
Effect.fn
```
或测试服务：阅读
```
references/SERVICES_LAYERS.md
```
。
运行时配置、环境变量、
```
ConfigProvider
```
或
```
layerConfig
```
：阅读
```
references/CONFIG.md
```
。
重试、重复、轮询、退避、抖动、感知速率限制的策略或循环执行：阅读
```
references/SCHEDULING.md
```
。
记忆化、按键TTL缓存、并发查询去重或请求批处理：阅读
```
references/CACHING.md
```
。
流、事件源、异步迭代器、队列/发布订阅、分页、背压或流消费者：阅读
```
references/STREAMS.md
```
。
对外HTTP调用、Effect HttpClient、状态处理或HTTP速率限制：阅读
```
references/HTTP_CLIENTS.md
```
。
Effect测试、时间、休眠、并发同步或模拟：阅读
```
references/TESTING.md
```
。

如果任务涉及多个分支，请在编辑前阅读所有匹配的文件。

Core Defaults

核心默认配置

Compose workflows with
```
Effect.gen(function* () { ... })
```
.
Define public service methods and non-trivial internal service methods with
```
Effect.fn("Domain.operation")
```
.
Use
```
Effect.fnUntraced
```
only for internal helpers where stack-frame/span metadata is intentionally unnecessary.
Prefer
```
Context.Service
```
for application services when the codebase has not standardized on another current service-tag style.

Build real service implementations with

Layer.effect(Service, Effect.gen(...))

and return

Service.of({ ... })

Model records with
```
Schema.Struct(...)
```
plus a same-name
```
interface
```
.
Model typed Effect errors with
```
Schema.TaggedErrorClass
```
.
Read runtime config through
```
Config
```
, not direct
```
process.env
```
access in application logic.
Use
```
Schedule
```
for retry, repeat, polling, pacing, and backoff policies.
Use
```
Stream
```
for effectful sources that emit many values over time and need pull, backpressure, interruption, or transformation.
Prefer Effect HTTP client modules for outgoing HTTP in Effect applications when their typed errors, layers, and client transforms are useful.
Prefer Effect-aware tests, explicit layers, and deterministic synchronization over sleeps.
Prefer decoders and
```
schema.makeEffect(...)
```
at untrusted boundaries; reserve throwing
```
schema.make(...)
```
for trusted construction, and never use casts to skip validation.

使用
```
Effect.gen(function* () { ... })
```
组合工作流。
使用
```
Effect.fn("Domain.operation")
```
定义公共服务方法和非简易的内部服务方法。
仅在有意不需要栈帧/跨度元数据的内部辅助函数中使用
```
Effect.fnUntraced
```
。
当代码库尚未标准化其他当前服务标签风格时，优先为应用服务使用
```
Context.Service
```
。

使用

Layer.effect(Service, Effect.gen(...))

构建真实的服务实现，并返回

Service.of({ ... })

。

使用
```
Schema.Struct(...)
```
搭配同名
```
interface
```
建模记录。
使用
```
Schema.TaggedErrorClass
```
建模类型化的Effect错误。
通过
```
Config
```
读取运行时配置，而非在应用逻辑中直接访问
```
process.env
```
。
使用
```
Schedule
```
处理重试、重复、轮询、调步和退避策略。
对于随时间emit多个值且需要拉取、背压、中断或转换的有副作用的源，使用
```
Stream
```
。
当Effect HTTP客户端模块的类型化错误、层和客户端转换有用时，优先在Effect应用中使用它们进行对外HTTP调用。
优先使用感知Effect的测试、显式层和确定性同步，而非休眠。
在不可信边界使用解码器和
```
schema.makeEffect(...)
```
；仅在可信构造中保留抛出式的
```
schema.make(...)
```
，绝不要使用类型断言跳过验证。

Quick Selection Guide

快速选择指南

Ordinary object record:
```
Schema.Struct(...)
```
plus same-name
```
interface
```
.
Scalar ID/value object: constrained branded schema.
Internal workflow decision or state:
```
Data.TaggedEnum<...>
```
plus
```
Data.taggedEnum<...>()
```
constructors and exhaustive
```
$match
```
.
Reusable boundary-crossing tagged variant:
```
Schema.TaggedStruct(...)
```
plus same-name
```
interface
```
.

Boundary-crossing tagged union:

Schema.TaggedUnion(...)

with

.cases

.guards

, and

.match

External/custom discriminator such as

type

Schema.Struct({ type: Schema.tag("variant"), ... })

plus

Schema.toTaggedUnion("type")

when union helpers are needed.

Expected typed failure:
```
Schema.TaggedErrorClass
```
.
Unknown boundary payload:
```
Schema.decodeUnknownEffect(...)
```
.

Service boundary:

Context.Service<Service, Interface>()(...)

plus

Layer.effect(...)

plus

Service.of(...)

Public or non-trivial internal service method:
```
Effect.fn("Domain.operation")
```
.
Runtime configuration:
```
Config
```
recipes read in layers; override with
```
ConfigProvider
```
in tests.
Event source:
```
Stream
```
consumed with
```
Stream.runForEach(...)
```
and forked with
```
Effect.forkScoped
```
in the owning layer.
Queue-backed event source:
```
Queue
```
for the producer boundary,
```
Stream.fromQueue(...)
```
for consumers.
Broadcast event source:
```
PubSub
```
/
```
Stream.fromPubSub(...)
```
or
```
SubscriptionRef
```
for latest-value state.
Polling worker:
```
runPass().pipe(Effect.repeat(Schedule.spaced(...)))
```
, with typed pass failures handled before repeat.

Retry transient operation:

Effect.retry(...)

Effect.retryOrElse(...)

with a bounded

Schedule

Keyed lookup cache with TTL and concurrent-lookup dedupe: prefer
```
Cache.make(...)
```
/ exit-aware
```
Cache.makeWith(...)
```
when their lifecycle and eviction model fit.

Memoize a single effect result:

Effect.cached(...)

Effect.cachedWithTTL(...)

Batch N keys into one backend call (only when a real batch endpoint exists):
```
Effect.request(...)
```
+
```
RequestResolver
```
.
HTTP request in an Effect application: prefer Effect
```
HttpClient
```
plus request/response schema decoding.
HTTP transient retry:
```
HttpClient.retryTransient(...)
```
.
Time-sensitive test:
```
TestClock
```
, not real sleeping.
Concurrent/background test synchronization:
```
Deferred
```
,
```
Queue
```
,
```
Latch
```
,
```
Ref
```
, or explicit test hooks.

普通对象记录：
```
Schema.Struct(...)
```
搭配同名
```
interface
```
。
标量ID/值对象：受约束的品牌化模式。
内部工作流决策或状态：
```
Data.TaggedEnum<...>
```
搭配
```
Data.taggedEnum<...>()
```
构造函数和穷举
```
$match
```
。
可复用的跨边界标签变体：
```
Schema.TaggedStruct(...)
```
搭配同名
```
interface
```
。

跨边界标签联合：

Schema.TaggedUnion(...)

配合

.cases

、

.guards

和

.match

。

外部/自定义判别符（如

type

）：

Schema.Struct({ type: Schema.tag("variant"), ... })

，当需要联合辅助工具时搭配

Schema.toTaggedUnion("type")

。

预期的类型化失败：
```
Schema.TaggedErrorClass
```
。
未知边界负载：
```
Schema.decodeUnknownEffect(...)
```
。

服务边界：

Context.Service<Service, Interface>()(...)

搭配

Layer.effect(...)

和

Service.of(...)

。

公共或非简易的内部服务方法：
```
Effect.fn("Domain.operation")
```
。
运行时配置：在层中读取
```
Config
```
配置；在测试中用
```
ConfigProvider
```
覆盖。
事件源：使用
```
Stream.runForEach(...)
```
消费，并在所属层中用
```
Effect.forkScoped
```
分叉。
队列支持的事件源：生产者边界使用
```
Queue
```
，消费者使用
```
Stream.fromQueue(...)
```
。
广播事件源：
```
PubSub
```
/
```
Stream.fromPubSub(...)
```
或用于最新值状态的
```
SubscriptionRef
```
。
轮询工作器：
```
runPass().pipe(Effect.repeat(Schedule.spaced(...)))
```
，在重复前处理类型化的执行失败。

重试临时操作：使用有界

Schedule

的

Effect.retry(...)

Effect.retryOrElse(...)

。

带TTL和并发查询去重的键值查找缓存：当
```
Cache.make(...)
```
/ 感知退出的
```
Cache.makeWith(...)
```
的生命周期和驱逐模型符合需求时优先使用。

记忆单个Effect结果：

Effect.cached(...)

Effect.cachedWithTTL(...)

。

将N个键批量处理为一次后端调用（仅当存在真实的批量端点时）：
```
Effect.request(...)
```
+
```
RequestResolver
```
。
Effect应用中的HTTP请求：优先使用Effect
```
HttpClient
```
搭配请求/响应模式解码。
HTTP临时重试：
```
HttpClient.retryTransient(...)
```
。
时间敏感的测试：
```
TestClock
```
，而非真实休眠。
并发/后台测试同步：
```
Deferred
```
、
```
Queue
```
、
```
Latch
```
、
```
Ref
```
或显式测试钩子。

Boundary Rules

边界规则

Keep HTTP handlers thin: decode input, read context, call services, map typed errors to transport responses.
Keep business rules in services or domain functions, not transport handlers.
Wrap HTTP clients, SDKs, CLIs, and external integrations in named effects at adapter boundaries.
Decode persisted rows with Schema or SQL-specific helpers when values are not trivially trusted.
Keep provider/network calls outside authoritative database transactions.
Catch or retry only when the current boundary has a truthful response.
Retry only when the operation has proven idempotency.
Let exhausted failures remain visible unless the boundary has a real fallback.

保持HTTP处理程序精简：解码输入、读取上下文、调用服务、将类型化错误映射为传输响应。
将业务规则放在服务或领域函数中，而非传输处理程序里。
在适配器边界将HTTP客户端、SDK、CLI和外部集成包装为命名的effects。
当值并非完全可信时，使用Schema或SQL特定的辅助工具解码持久化行。
将提供者/网络调用放在权威数据库事务之外。
仅当当前边界有真实响应时才捕获或重试。
仅当操作已被证明是幂等的时才重试。
除非边界有真实的回退方案，否则让耗尽的失败保持可见。

Do Nots

禁止事项

Do not use
```
as any
```
, non-null assertions, or unchecked casts to silence Effect typing problems.
Do not introduce
```
Schema.Class
```
or
```
Schema.TaggedClass
```
as default app data-modeling patterns.
Do not hand-roll
```
_tag
```
error classes when
```
Schema.TaggedErrorClass
```
fits.
Do not use cause-level recovery when typed-error recovery is enough.
Do not use
```
Layer.mergeAll(...)
```
or
```
provideMerge(...)
```
as blind make-it-compile tools.
Do not hide required application authority, credentials, persistence, transports, or external services behind
```
Context.Reference
```
defaults.
Do not add arbitrary
```
Effect.sleep(...)
```
to tests when a deterministic synchronization primitive is available.
Do not hand-roll Map/TTL/prune caches or in-flight dedupe when
```
effect/Cache
```
fits.

不要使用
```
as any
```
、非空断言或未检查的类型断言来掩盖Effect的类型问题。
不要将
```
Schema.Class
```
或
```
Schema.TaggedClass
```
作为应用数据建模的默认模式。
当
```
Schema.TaggedErrorClass
```
适用时，不要手动编写
```
_tag
```
错误类。
当类型化错误恢复足够时，不要使用原因级恢复。
不要将
```
Layer.mergeAll(...)
```
或
```
provideMerge(...)
```
作为盲目让代码编译的工具。
不要将所需的应用权限、凭据、持久化、传输或外部服务隐藏在
```
Context.Reference
```
默认值之后。
当有确定性同步原语可用时，不要在测试中添加任意的
```
Effect.sleep(...)
```
。
当
```
effect/Cache
```
适用时，不要手动编写Map/TTL/修剪缓存或进行飞行中请求去重。