effect-patterns-hub

Effect 模式集

目的：快速访问 EffectPatterns 仓库中精选的 130 多种 Effect-TS 模式。使用此技能查找特定实现模式、比较不同方法并参考最佳实践。

触发条件

• 查找特定的 Effect 模式或惯用写法
• 需要 Effect 概念的实际示例
• 想查看同一问题的多种解决方法
• 比较实现策略
• 学习新的 Effect 功能

模式库位置

本地模式：.claude/skills/effect-patterns-hub/patterns/
文档：docs/effect-patterns/
数量：130 多种 MDX 格式的模式

快速决策树

我需要……

创建 Effect

• 从值创建 → constructor-succeed-some-right.mdx
• 从同步代码创建 → constructor-sync-async.mdx
• 从 Promise 创建 → constructor-try-trypromise.mdx
• 从可空值创建 → constructor-from-nullable-option-either.mdx
• 创建预先解析的 Effect → create-pre-resolved-effect.mdx

转换与组合

• 映射值 → combinator-map.mdx
• 链接 Effect → combinator-flatmap.mdx
• 按顺序执行操作 → combinator-sequencing.mdx
• 合并值 → combinator-zip.mdx
• 过滤 → combinator-filter.mdx
• 条件逻辑 → combinator-conditional.mdx
• 处理集合 → combinator-foreach-all.mdx

控制流

• 顺序逻辑 → write-sequential-code-with-gen.mdx
• 业务逻辑 → use-gen-for-business-logic.mdx
• 管道组合 → use-pipe-for-composition.mdx
• 分支工作流 → conditionally-branching-workflows.mdx
• 组合子 → control-flow-with-combinators.mdx
• 重复执行 → control-repetition-with-schedule.mdx

错误处理

• 定义错误 → define-tagged-errors.mdx
• 捕获特定错误 → pattern-catchtag.mdx
• 处理所有错误 → handle-errors-with-catch.mdx
• 重试操作 → retry-based-on-specific-errors.mdx
• 处理不稳定的操作 → handle-flaky-operations-with-retry-timeout.mdx
• 映射错误 → mapping-errors-to-fit-your-domain.mdx
• 处理意外错误 → handle-unexpected-errors-with-cause.mdx
• API 错误 → handle-api-errors.mdx

Concurrency

• Parallel execution → run-effects-in-parallel-with-all.mdx
• Background tasks → run-background-tasks-with-fork.mdx
• Process collections → process-collection-in-parallel-with-foreach.mdx
• Race effects → race-concurrent-effects.mdx
• Fibers explained → understand-fibers-as-lightweight-threads.mdx
• Decouple with queues → decouple-fibers-with-queue-pubsub.mdx
• Polling → poll-for-status-until-task-completes.mdx
• Graceful shutdown → implement-graceful-shutdown.mdx

Services & Dependency Injection

• Model dependencies → model-dependencies-as-services.mdx
• Understand layers → understand-layers-for-dependency-injection.mdx
• Scoped services → scoped-service-layer.mdx
• Composable modules → organize-layers-into-composable-modules.mdx
• Compose scoped layers → compose-scoped-layers.mdx
• Provide config → provide-config-layer.mdx
• Caching wrapper → add-caching-by-wrapping-a-layer.mdx

Resource Management

• Bracket pattern → safely-bracket-resource-usage.mdx
• Scope management → manage-resource-lifecycles-with-scope.mdx
• Manual scope → manual-scope-management.mdx
• Scoped resources runtime → create-managed-runtime-for-scoped-resources.mdx

Streaming

• Process streaming data → process-streaming-data-with-stream.mdx
• From iterable → stream-from-iterable.mdx
• From file → stream-from-file.mdx
• From paginated API → stream-from-paginated-api.mdx
• Concurrent processing → stream-process-concurrently.mdx
• Batch processing → stream-process-in-batches.mdx
• Collect results → stream-collect-results.mdx
• Run for effects → stream-run-for-effects.mdx
• Manage resources → stream-manage-resources.mdx
• Retry on failure → stream-retry-on-failure.mdx

Schema & Validation

• Define contracts → define-contracts-with-schema.mdx
• Parse/decode → parse-with-schema-decode.mdx
• Transform data → transform-data-with-schema.mdx
• Validate body → validate-request-body.mdx
• Brand types → brand-model-domain-type.mdx
• Brand validation → brand-validate-parse.mdx
• Config schema → define-config-schema.mdx

数据类型

• Option → data-option.mdx、model-optional-values-with-option.mdx
• Either → data-either.mdx、accumulate-multiple-errors-with-either.mdx
• Chunk → data-chunk.mdx、use-chunk-for-high-performance-collections.mdx
• Array → data-array.mdx
• HashSet → data-hashset.mdx
• Duration → data-duration.mdx、representing-time-spans-with-duration.mdx
• DateTime → data-datetime.mdx、beyond-the-date-type.mdx
• BigDecimal → data-bigdecimal.mdx
• Cause → data-cause.mdx
• Exit → data-exit.mdx
• Ref → data-ref.mdx、manage-shared-state-with-ref.mdx
• Redacted → data-redacted.mdx
• Case → data-case.mdx
• Class → data-class.mdx
• Struct → data-struct.mdx
• Tuple → data-tuple.mdx

模式匹配

• Match API → pattern-match.mdx
• Effectful match → pattern-matcheffect.mdx
• Tag matching → pattern-matchtag.mdx
• Option/Either 检查 → pattern-option-either-checks.mdx

HTTP 与 Web

• 基本 HTTP 服务端 → build-a-basic-http-server.mdx
• 启动服务端 → launch-http-server.mdx
• 处理 GET 请求 → handle-get-request.mdx
• HTTP 客户端请求 → make-http-client-request.mdx
• 可测试的 HTTP 客户端 → create-a-testable-http-client-service.mdx
• JSON 响应 → send-json-response.mdx
• 路径参数 → extract-path-parameters.mdx
• 为路由提供依赖 → provide-dependencies-to-routes.mdx

测试

• 模拟依赖 → mocking-dependencies-in-tests.mdx
• 使用 Default layer → use-default-layer-for-tests.mdx
• 让测试适应代码 → write-tests-that-adapt-to-application-code.mdx

可观测性

• 结构化日志记录 → leverage-structured-logging.mdx、observability-structured-logging.mdx
• 跟踪跨度 → trace-operations-with-spans.mdx、observability-tracing-spans.mdx
• 自定义指标 → add-custom-metrics.mdx、observability-custom-metrics.mdx
• OpenTelemetry → observability-opentelemetry.mdx
• Effect.fn 插桩 → observability-effect-fn.mdx

运行时与执行

• runPromise → execute-with-runpromise.mdx
• runSync → execute-with-runsync.mdx
• runFork → execute-long-running-apps-with-runfork.mdx
• 可复用运行时 → create-reusable-runtime-from-layers.mdx

配置

• 访问配置 → access-config-in-context.mdx
• 定义架构 → define-config-schema.mdx
• 提供层 → provide-config-layer.mdx

时间与调度

• 当前时间 → accessing-current-time-with-clock.mdx
• 时长 → representing-time-spans-with-duration.mdx
• 日期时间 → beyond-the-date-type.mdx
• 调度重复执行 → control-repetition-with-schedule.mdx

项目设置

• 新建项目 → setup-new-project.mdx
• 编辑器 LSP → supercharge-your-editor-with-the-effect-lsp.mdx
• AI Agent MCP → teach-your-ai-agents-effect-with-the-mcp-server.mdx

高级概念

• 结构相等性 → comparing-data-by-value-with-structural-equality.mdx
• Effect 通道 → understand-effect-channels.mdx
• Effect 是惰性的 → effects-are-lazy.mdx
• 区分未找到与错误 → distinguish-not-found-from-errors.mdx
• Promise 问题 → solve-promise-problems-with-effect.mdx
• 避免过长的链式调用 → avoid-long-andthen-chains.mdx

模式分类

按技能等级

初级（入门）

• 构造器模式（succeed、fail、sync、async）
• 基本组合器（map、flatMap、tap）
• 简单错误处理（catch、catchTag）
• Effect.gen 基础
• runPromise/runSync

中级（构建应用）

• 服务与层
• Schema 校验
• HTTP 服务端与客户端
• 资源管理
• 并发基础（Effect.all、fork）
• 使用 mock 进行测试

高级（生产系统）

• 复杂的层组合
• 自定义运行时
• 流水线处理
• 优雅关闭
• OpenTelemetry 集成
• 性能优化（Chunk、Ref）

按使用场景

领域建模

• Schema 定义
• 品牌类型
• 带标签的错误
• 用于可选值或可能失败值的 Option/Either

API 开发

• HTTP 服务端设置
• 路由处理
• 请求校验
• 错误处理
• 响应格式化

数据处理

• 流处理
• 批处理操作
• 并行处理
• 资源安全的流水线

应用架构

• 服务层设计
• 依赖注入
• 模块组合
• 配置管理

测试

• Mock 层
• 测试工具
• 可测试的服务

可观测性

• 结构化日志
• 分布式追踪
• 自定义指标
• 性能监控

搜索模式

按关键词

使用 Grep 按关键词搜索模式：

# Find patterns about error handling
grep -l "error" patterns/*.mdx

# Find patterns about concurrency
grep -l "concurrent\|parallel\|fiber" patterns/*.mdx

# Find patterns about HTTP
grep -l "http\|server\|client" patterns/*.mdx

# Find patterns about testing
grep -l "test\|mock" patterns/*.mdx

按 Frontmatter 标签

所有模式都包含元数据：

• title：易读的名称
• id：唯一标识符（不含扩展名的文件名）
• skillLevel：初级、中级、高级
• useCase：领域建模、错误处理、并发等
• summary：简要说明
• tags：用于搜索的关键词
• related：相关模式的链接

常见搜索

“如何从……创建 Effect？”

• → 搜索构造器模式：grep -l "constructor" patterns/*.mdx
• → 查看 constructor-*.mdx 文件

“如何处理……时的错误？”

• → 搜索错误处理：grep -l "error\|catch\|retry" patterns/*.mdx
• → 查看 handle-*.mdx 和 pattern-catchtag.mdx

“如何并发运行多个任务？”

• → 搜索并发：grep -l "concurrent\|parallel\|all\|fork" patterns/*.mdx
• → 查看 run-effects-in-parallel-with-all.mdx

“如何使用服务？”

• → 搜索服务：grep -l "service\|layer\|dependency" patterns/*.mdx
• → 查看 model-dependencies-as-services.mdx、understand-layers-for-dependency-injection.mdx

“如何验证数据？”

• → 搜索架构：grep -l "schema\|validate\|parse" patterns/*.mdx
• → 查看 define-contracts-with-schema.mdx、parse-with-schema-decode.mdx

与其他技能集成

Foundations → Patterns Hub

需要基础概念的具体示例时，请查看模式：

• effect-foundations 讲解概念 → patterns 展示实现方式

Architect → Patterns Hub

设计系统时，请参考架构模式：

• Layer 组合 → organize-layers-into-composable-modules.mdx
• 服务设计 → model-dependencies-as-services.mdx
• 有作用域的资源 → scoped-service-layer.mdx

Engineer → Patterns Hub

实现功能时，查找相关模式：

• HTTP 端点 → handle-get-request.mdx、validate-request-body.mdx
• 错误处理 → retry-based-on-specific-errors.mdx
• 并发 → run-effects-in-parallel-with-all.mdx

Tester → Patterns Hub

编写测试时，请参考测试模式：

• 模拟服务 → mocking-dependencies-in-tests.mdx
• 测试 Layer → use-default-layer-for-tests.mdx
• 可测试的设计 → write-tests-that-adapt-to-application-code.mdx

使用工作流

1. 确定需求：“我需要用 Effect [做某事]”
2. 查看决策树：查找上方的相关部分
3. 阅读模式：使用 Read 工具读取模式文件
4. 结合上下文调整：将模式应用于具体用例
5. 查看相关内容：沿着模式 frontmatter 中的 related 链接查找
6. 咨询 Agent：如果不清楚，请使用 @effect-engineer 或 @effect-architect

反模式检测

如果你发现自己在：

• 使用命令式循环 → 查看 process-collection-in-parallel-with-foreach.mdx
• 混用 promises 和 Effects → 查看 constructor-try-trypromise.mdx、solve-promise-problems-with-effect.mdx
• 编写很长的 andThen 链 → 查看 avoid-long-andthen-chains.mdx、use-gen-for-business-logic.mdx
• 泄漏需求 → 查看 model-dependencies-as-services.mdx
• 手动清理资源 → 查看 safely-bracket-resource-usage.mdx

模式文件结构

每个模式文件都遵循以下结构：

---
title: Human-readable title
id: kebab-case-id
skillLevel: beginner | intermediate | advanced
useCase: primary-use-case
summary: Brief description
tags:
  - keyword1
  - keyword2
related:
  - related-pattern-id-1
  - related-pattern-id-2
author: Author name
---

# Title

## Guideline
What to do

## Rationale
Why do it this way

## Good Example
✅ Recommended approach

## Bad Example
❌ What to avoid

## Related Patterns
Links to related patterns

维护

模式从 EffectPatterns repository 同步而来。

更新模式：

cd /tmp
git clone --depth=1 https://github.com/PaulJPhilp/EffectPatterns.git
cp -r EffectPatterns/content/published/* /Users/pooks/Dev/crate/.claude/skills/effect-patterns-hub/patterns/
cp -r EffectPatterns/content/published/* /Users/pooks/Dev/crate/docs/effect-patterns/

总结

• 涵盖所有 Effect-TS 概念的 130 多种模式
• 便于快速查找模式的决策树
• 与现有技能和 Agent 集成
• 可按关键词、用例和技能级别搜索
• 展示良好与不良实践的示例
• 便于深入探索的相关模式

将此技能作为“如何用 Effect……？”的首选参考。