菜单
Effect v4 模式指南。当需要创建 Effect 服务、定义错误类型、编写 Effect 程序、管理 Layer 组合、或使用 Effect 封装异步操作时使用
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | effect-v4 |
| description | Effect v4 模式指南。当需要创建 Effect 服务、定义错误类型、编写 Effect 程序、管理 Layer 组合、或使用 Effect 封装异步操作时使用 |
| argument-hint | [service/error/layer/pattern] |
本 skill 为 Effect v4 (4.0.0-beta.48) 在本项目中的使用提供规范化指南。
Context.Service、Data.TaggedError、Layer）src/lib/infrastructure/effect/
├── index.ts # Barrel exports
├── errors.ts # Data.TaggedError 定义
├── services/ # Context.Service 定义
│ ├── db.ts # DbService
│ ├── logger.ts # LoggerService
│ └── bullmq.ts # BullMQService
└── layers/
└── live.ts # InfraLayer = Layer.mergeAll(...)
| 类别 | DO | DON'T |
|---|---|---|
| Service 定义 | Context.Service<Self, Shape>()("tag") | Effect.Service (v3 API) |
| Service 构造 | Layer.succeed(Tag, instance) / Layer.effect(Tag, ...) | 在使用处 Effect.provide |
| 错误类型 | Data.TaggedError("Tag")<{ fields }> | Schema.TaggedError / 普通 Error |
| 错误处理 | catchTag / catchTags 按标签匹配 | catchAll / mapError 丢失类型 |
| 追踪函数 | Effect.fn("Service.method")(function* ...) | 匿名 generator 无追踪名 |
| 异步包装 | Effect.tryPromise({ try, catch }) | Effect 内部 raw await |
| 错误抛出 | yield* Effect.fail(new XxxError(...)) | Effect.gen 内 throw |
| Layer 组合 | Layer.mergeAll 平铺同级 | 深层嵌套 Layer.provide |
| Layer 链式 | Layer.provideMerge 增量组合 | 多层 Layer.provide（类型爆炸） |
| 执行边界 | Effect.runPromise 仅在 Hono handler 入口 | Service 内部 runPromise |
| v3 | v4 | 说明 |
|---|---|---|
Effect.Service<T>()("name", { accessors, dependencies, effect }) | Context.Service<T, Shape>()("name") + Layer.succeed/effect | Service 类只是标签，Layer 独立构造 |
accessors: true → Service.method() | yield* ServiceTag → service.method() | 先获取 service 实例再调方法 |
dependencies: [Dep.Default] | Layer.provide(depLayer) / Layer.provideMerge(depLayer) | 依赖关系在 Layer 组合时声明 |
Schema.TaggedError<T>()("tag", { fields }) | Data.TaggedError("tag")<{ fields }> | 不需要 Schema 字段，用 TS readonly |
HttpApiSchema.annotations({ status: 404 }) | Hono handler 中 c.json(Resp.fail(...), 404) | HTTP 状态码在路由层处理 |
Config.string("KEY") | import env from "@/env" | 项目用 Zod 验证的 env |
Effect.log("msg") | logger.info({ data }, "[Module]: msg") | 项目用 Pino |
Schema.Option(Schema.String) | field: string | null | 项目用 Drizzle/Zod 可空类型 |
Effect 在本项目中的定位是 基础设施编排层，不是全栈框架。边界清晰：
Hono Handler (async/await)
└─ Effect.runPromise(program) ← 边界：进入 Effect 世界
└─ Effect.gen(function* () {
const db = yield* DbService; ← 获取 service
const result = yield* Effect.tryPromise(...); ← 异步操作
return result;
})
入口点（允许 Effect.runPromise）：
Service 内部（禁止 Effect.runPromise）：
Effect.Effect<A, E, R>yield* 组合其他 EffectEffect.tryPromise 包装异步创建或修改 BullMQ 队列任务。当需要创建新队列、添加任务类型、注册 Worker、设置定时任务、或用户请求"添加后台任务/队列处理"时使用
创建或修改一个新的 API tier。当用户请求“新增 tier / 创建 partner tier / 新增 merchant 端 / 新增 tenant 端 / 新增 API 端 / 新增一套路由层”时使用。目标是在不修改框架核心的前提下，为新 tier 补齐配置、中间件、类型别名、路由入口和测试。
创建或修改 CRUD 模块。当需要创建新的增删改查 API、修改现有路由模块、添加新字段、新增接口、或用户请求"创建/修改 XX 管理"时使用
创建或修改数据库 Schema。当需要创建新表、修改表结构、定义字段、设置索引约束、或涉及 Drizzle ORM / drizzle-zod 操作时使用
Drizzle ORM v1 关系查询指南。当需要定义 Relations v2、编写关系查询、使用 through 多对多、预定义过滤器、或从旧版 Drizzle 迁移时使用
Implement tasks from an OpenSpec change (Experimental)