effect-ts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Effect Expert

Effect专家

Expert guidance for programming with the Effect library, covering error handling, dependency injection, composability, and testing patterns.

针对Effect库编程的专家指导，涵盖错误处理、依赖注入、可组合性和测试模式。

Prerequisite

前置条件

Before doing any other Effect-related work, check that

./.repos/effect

exists at the root of the repository where the skill is being used.

If it does not exist, stop and prompt the user with the setup task documented in

./references/setup.md

在开展任何与Effect相关的工作之前，请检查使用此Skill的代码仓库根目录下是否存在

./.repos/effect

。

如果不存在，请停止当前操作，并提示用户按照

./references/setup.md

中记录的设置任务进行配置。

Research Strategy

研究策略

Effect has many ways to accomplish the same task. Proactively research best practices when working with Effect patterns, especially for moderate to high complexity tasks.

Use the local guides in

./references/

first. They are the preferred source for best practices, conventions, and common implementation patterns.

Only go directly to the vendored Effect repo when:

the guides do not cover the question
you need exact API details or signatures
you need deeper implementation details
you need to verify a behavior against the source

Effect有多种方式可完成同一任务。在处理Effect模式相关工作时，尤其是复杂度中等或较高的任务，需主动研究最佳实践。

优先使用

./references/

中的本地指南，它们是获取最佳实践、约定和常见实现模式的首选来源。

仅在以下情况下直接查看 vendored Effect 仓库：

指南未覆盖相关问题
需要确切的API细节或签名
需要更深入的实现细节
需要根据源码验证行为

Research Sources

研究来源

Local skill guides first. Start with the relevant files in
```
./references/
```
before doing deeper research.
Codebase patterns second. Examine similar patterns in the current project before implementing. If Effect patterns already exist, follow them for consistency. If no patterns exist, skip this step.
Effect source code last. For gaps in the guides, complex type errors, unclear behavior, or implementation details, examine the vendored Effect source at
```
./.repos/effect/packages/effect/src/
```
.

首先查看本地Skill指南。在进行深入研究之前，先从
```
./references/
```
中的相关文件开始。
其次查看代码库模式。在实现之前，检查当前项目中的类似模式。如果已存在Effect模式，请遵循这些模式以保持一致性。如果不存在此类模式，则跳过此步骤。
最后查看Effect源码。对于指南中的空白内容、复杂类型错误、不明确的行为或实现细节，请查看
```
./.repos/effect/packages/effect/src/
```
下的vendored Effect源码。

When To Research

研究时机

Always research for services, layers, or complex dependency injection.
Always research for error handling with multiple error types or complex error hierarchies.
Always research for stream-based operations and reactive patterns.
Always research for resource management with scoped effects and cleanup.
Always research for concurrent or performance-critical code.
Always research for unfamiliar testing patterns.
Research when needed for complex refactors from promises or try/catch into Effect.
Research when needed for new service dependencies or layer restructuring.
Research when needed for custom error types or extensions of existing error hierarchies.
Research when needed for integrations with external systems such as databases, APIs, or third-party services.

处理服务、层或复杂依赖注入时，必须进行研究。
处理涉及多种错误类型或复杂错误层级的错误处理时，必须进行研究。
处理基于流的操作和响应式模式时，必须进行研究。
处理涉及作用域Effect和清理的资源管理时，必须进行研究。
处理并发或性能关键型代码时，必须进行研究。
处理不熟悉的测试模式时，必须进行研究。
当需要将Promise或try/catch代码重构为Effect代码的复杂场景时，按需进行研究。
当需要新增服务依赖或重构层结构时，按需进行研究。
当需要自定义错误类型或扩展现有错误层级时，按需进行研究。
当需要与数据库、API或第三方服务等外部系统集成时，按需进行研究。

Research Approach

研究方法

Focus on canonical, readable, and maintainable solutions rather than clever optimizations.
Verify suggested approaches against existing codebase patterns when those patterns exist.
When multiple approaches are possible, prefer the most idiomatic Effect solution supported by the codebase and the vendored source.

优先选择规范、可读且可维护的解决方案，而非巧妙的优化方案。
当存在现有代码库模式时，验证建议的方法是否符合这些模式。
当有多种方法可选时，优先选择代码库和vendored源码支持的最符合Effect风格的解决方案。

Codebase Pattern Discovery

代码库模式发现

When working in a project that uses Effect, check for existing patterns before implementing new code:

Search for Effect imports and existing module usage to understand current conventions.
Identify how services and layers are structured in the project.
Note how errors are defined and propagated.
Examine how Effect code is tested in the project.

If no Effect patterns exist in the codebase, proceed using canonical patterns from the vendored Effect source and examples. Do not block on missing codebase patterns.

在使用Effect的项目中工作时，在实现新代码之前，请检查现有模式：

搜索Effect导入语句和现有模块用法，以了解当前约定。
确定项目中服务和层的结构方式。
记录错误的定义和传播方式。
检查项目中Effect代码的测试方式。

如果代码库中不存在Effect模式，则使用vendored Effect源码和示例中的规范模式进行开发。无需因缺少代码库模式而停滞。

Feature Discovery

功能发现

When you need to discover available Effect modules, packages, or capabilities, search

./references/features.md

first.

Use it to identify the right package or module for a task.
Use the listed repo paths to jump directly into the vendored source under
```
./.repos/effect
```
.
Use it before inventing custom abstractions when Effect may already provide the functionality.

当需要查找可用的Effect模块、包或功能时，请首先查看

./references/features.md

。

使用它来确定适合任务的包或模块。
使用列出的仓库路径直接跳转到
```
./.repos/effect
```
下的vendored源码。
在Effect可能已提供相关功能的情况下，不要自行创建自定义抽象。

Guide Discovery

指南发现

When the task touches one of these areas, consult the matching guide before implementing:

```
./references/guide-effect.md
```
for core
```
Effect
```
usage patterns, common constructors, composition, provisioning, and runtime boundaries
```
./references/guide-error-handling.md
```
for defining errors, schema-based errors, failure handling, defects, and interrupts
```
./references/guide-layers.md
```
for services, layer construction, composition, and provisioning patterns
```
./references/guide-observability.md
```
for
```
Effect.fn
```
, spans, logging, metrics, and telemetry wiring
```
./references/guide-retries.md
```
for retry policies, retry conditions, fallback strategies, and
```
ExecutionPlan
```
```
./references/guide-schedule.md
```
for retries, repeats, backoff, polling, cron, and schedule composition
```
./references/guide-schema.md
```
for schema design, transformations, unions, recursion, opaque/branded types, and schema best practices
```
./references/guide-sql.md
```
for Effect SQL usage, transactions, resolvers, schema-aware SQL, and migrations
```
./references/guide-testing.md
```
for detailed
```
@effect/vitest
```
usage, layered test setup, property tests, and test services

These guides should be treated as the default implementation guidance. Do not skip them and jump straight to

./.repos/effect

unless you need source-level confirmation or the guides do not answer the question.

当任务涉及以下领域时，请在实现前查阅对应的指南：

```
./references/guide-effect.md
```
：核心
```
Effect
```
使用模式、常见构造函数、组合、配置和运行时边界
```
./references/guide-error-handling.md
```
：错误定义、基于Schema的错误、失败处理、缺陷和中断
```
./references/guide-layers.md
```
：服务、层构建、组合和配置模式
```
./references/guide-observability.md
```
：
```
Effect.fn
```
、追踪、日志、指标和遥测连接
```
./references/guide-retries.md
```
：重试策略、重试条件、回退策略和
```
ExecutionPlan
```
```
./references/guide-schedule.md
```
：重试、重复、退避、轮询、定时任务和调度组合
```
./references/guide-schema.md
```
：Schema设计、转换、联合、递归、不透明/品牌类型和Schema最佳实践
```
./references/guide-sql.md
```
：Effect SQL用法、事务、解析器、Schema感知SQL和迁移
```
./references/guide-testing.md
```
：
```
@effect/vitest
```
详细用法、分层测试设置、属性测试和测试服务

这些指南应作为默认的实现指导。除非需要源码级确认或指南未回答相关问题，否则不要跳过它们直接查看

./.repos/effect

。

Effect Principles

Effect原则

Apply these core principles when writing Effect code.

编写Effect代码时，请遵循这些核心原则。

Installation

安装

When installing Effect packages in a user repository:

use
```
effect@beta
```
keep all
```
@effect/*
```
packages on aligned versions
install only the packages needed for the user's runtime and actual task

在用户代码仓库中安装Effect包时：

使用
```
effect@beta
```
保持所有
```
@effect/*
```
包的版本一致
仅安装用户运行时和实际任务所需的包

Version Rules

版本规则

```
effect
```
should be installed as
```
effect@beta
```
if you install any
```
@effect/*
```
package, make sure all
```
@effect/*
```
packages use matching versions
do not mix unrelated
```
@effect/*
```
versions in the same project

```
effect
```
应安装为
```
effect@beta
```
如果安装任何
```
@effect/*
```
包，请确保所有
```
@effect/*
```
包使用匹配的版本
不要在同一项目中混合使用不相关的
```
@effect/*
```
版本

Package Selection

包选择

Choose packages based on the runtime and the work being done.

core library:
```
effect@beta
```
Node.js runtime needs: install the matching
```
@effect/platform-node
```
browser runtime needs: install the matching
```
@effect/platform-browser
```
Bun runtime needs: install the matching
```
@effect/platform-bun
```
Vitest integration needs: install the matching
```
@effect/vitest
```
OpenTelemetry integration needs: install the matching
```
@effect/opentelemetry
```

Install additional

@effect/*

packages only when the user task actually needs them.

根据运行时和正在进行的工作选择包。

核心库：
```
effect@beta
```
Node.js运行时需求：安装匹配的
```
@effect/platform-node
```
浏览器运行时需求：安装匹配的
```
@effect/platform-browser
```
Bun运行时需求：安装匹配的
```
@effect/platform-bun
```
Vitest集成需求：安装匹配的
```
@effect/vitest
```
OpenTelemetry集成需求：安装匹配的
```
@effect/opentelemetry
```

仅当用户任务实际需要时，才安装额外的

@effect/*

包。

Practical Rule

实用规则

start with
```
effect@beta
```
add
```
@effect/*
```
packages as needed by runtime and features
keep the full installed Effect package set version-aligned

从
```
effect@beta
```
开始
根据运行时和功能需求添加
```
@effect/*
```
包
保持已安装的所有Effect包版本一致

Error Handling

错误处理

Use Effect's typed error system instead of throwing exceptions.
Define descriptive error types with proper error propagation.
Prefer
```
Schema.TaggedErrorClass
```
when the error can be schema-defined.
Use
```
Effect.fail
```
,
```
Effect.catchTag
```
, and
```
Effect.catch
```
for error control flow.

使用Effect的类型化错误系统，而非抛出异常。
定义具有适当错误传播机制的描述性错误类型。
当错误可通过Schema定义时，优先使用
```
Schema.TaggedErrorClass
```
。
使用
```
Effect.fail
```
、
```
Effect.catchTag
```
和
```
Effect.catch
```
进行错误控制流管理。

Dependency Injection

依赖注入

Implement dependency injection using services and layers.
Define services with
```
Context.Tag
```
.
Compose layers with
```
Layer.merge
```
and
```
Layer.provide
```
.
Use
```
Effect.provide
```
to inject dependencies at the edge, avoid providing locally.
Keep services encapsulated; avoid exporting trivial accessor wrappers that only forward to one service method.

使用服务和层实现依赖注入。
使用
```
Context.Tag
```
定义服务。
使用
```
Layer.merge
```
和
```
Layer.provide
```
组合层。
使用
```
Effect.provide
```
在边缘注入依赖，避免在本地提供依赖。
保持服务封装；避免仅转发单个服务方法的琐碎访问器包装器。

Composability

可组合性

Leverage Effect composability for complex operations.

Use appropriate constructors such as

Effect.succeed

Effect.fail

Effect.tryPromise

Effect.try

, and

Effect.sync

Apply proper resource management with scoped effects.
Chain operations with
```
Effect.flatMap
```
,
```
Effect.map
```
, and
```
Effect.tap
```
.

利用Effect的可组合性处理复杂操作。

使用合适的构造函数，如

Effect.succeed

、

Effect.fail

、

Effect.tryPromise

、

Effect.try

和

Effect.sync

。

使用作用域Effect实现适当的资源管理。
使用
```
Effect.flatMap
```
、
```
Effect.map
```
和
```
Effect.tap
```
链接操作。

Business Logic Functions

业务逻辑函数

Prefer
```
Effect.fn
```
for reusable business-logic functions that return
```
Effect
```
.
Prefer
```
Effect.fn
```
over raw
```
Effect.gen
```
definitions even when the function takes no arguments.
If you do not want an explicit named span, use
```
Effect.fn
```
without a span name.
Do not use
```
Effect.fnUntraced
```
as the default.
Use
```
Effect.fnUntraced
```
only for edge cases with a concrete low-level reason, such as measured hot-path overhead.

对于返回
```
Effect
```
的可重用业务逻辑函数，优先使用
```
Effect.fn
```
。
即使函数不接受参数，也优先使用
```
Effect.fn
```
而非原始的
```
Effect.gen
```
定义。
如果不需要显式命名追踪，请使用不带追踪名称的
```
Effect.fn
```
。
不要将
```
Effect.fnUntraced
```
作为默认选项。
仅在有具体底层原因（如测量热点路径开销）的边缘情况下使用
```
Effect.fnUntraced
```
。

TypeScript Preferences

TypeScript偏好

Never use
```
any
```
.
Never use
```
as
```
casts.
Never use unsafe type assertions or escape hatches.
Never use
```
namespace
```
.
Prefer correct typing, schema-driven decoding, narrowing, and proper generic constraints instead of forcing types.
If a value comes from an external boundary, validate or decode it instead of asserting its type.
If a type is hard to express, simplify the design or introduce a properly typed helper instead of using unsafe TypeScript.
For layers, do not hide them inside
```
namespace
```
blocks. Prefer either
```
static
```
members on the service class or plain exported layer constants.

绝不使用
```
any
```
。
绝不使用
```
as
```
类型转换。
绝不使用不安全的类型断言或逃逸舱口。
绝不使用
```
namespace
```
。
优先选择正确的类型标注、基于Schema的解码、类型收窄和适当的泛型约束，而非强制类型。
如果值来自外部边界，请验证或解码它，而非断言其类型。
如果某个类型难以表达，请简化设计或引入类型正确的辅助工具，而非使用不安全的TypeScript语法。
对于层，不要将它们隐藏在
```
namespace
```
块中。优先选择在服务类上使用
```
static
```
成员或直接导出层常量。

Code Quality

代码质量

Write type-safe code that leverages Effect's type system.
Use
```
Effect.gen
```
for readable sequential code.
Implement proper testing patterns using Effect testing utilities.
Prefer existing Effect primitives before introducing custom helpers.
Prefer
```
Schema.Class
```
/
```
Schema.TaggedClass
```
variants over plain
```
Schema.Struct
```
for named reusable schemas when possible.

编写利用Effect类型系统的类型安全代码。
使用
```
Effect.gen
```
编写可读性强的顺序代码。
使用Effect测试工具实现适当的测试模式。
在引入自定义辅助工具之前，优先使用现有的Effect原语。
对于命名的可重用Schema，尽可能优先使用
```
Schema.Class
```
/
```
Schema.TaggedClass
```
变体，而非普通的
```
Schema.Struct
```
。

Explaining Solutions

解决方案说明

When providing solutions, explain the Effect concepts being used and why they fit the specific use case. If you encounter patterns not covered in local references, prefer consistency with the codebase when possible and otherwise rely on the vendored Effect source.

提供解决方案时，请解释所使用的Effect概念以及它们为何适合特定用例。如果遇到本地参考资料未涵盖的模式，请尽可能与代码库保持一致，否则依赖vendored Effect源码。

References

参考资料

```
./references/features.md
```
```
./references/guide-effect.md
```
```
./references/guide-error-handling.md
```
```
./references/guide-layers.md
```
```
./references/guide-observability.md
```
```
./references/guide-retries.md
```
```
./references/guide-schedule.md
```
```
./references/guide-schema.md
```
```
./references/guide-sql.md
```
```
./references/guide-testing.md
```
```
./references/setup.md
```

```
./references/features.md
```
```
./references/guide-effect.md
```
```
./references/guide-error-handling.md
```
```
./references/guide-layers.md
```
```
./references/guide-observability.md
```
```
./references/guide-retries.md
```
```
./references/guide-schedule.md
```
```
./references/guide-schema.md
```
```
./references/guide-sql.md
```
```
./references/guide-testing.md
```
```
./references/setup.md
```