用途 该技能用于把单个 oRPC 过程从经典 async handler 迁移为 Effect-backed 实现,同时保持路由形态、响应契约和授权语义不变。它面向增量迁移场景,建议一次只迁移一个过程,并让每次提交或 PR 只包含一个过程的转换。
使用前提 目标过程应只使用已有 Effect 封装的服务。需要先检查过程使用了哪些服务,并查看 apps/riptide-api/src/effects/app-runtime.ts 中的 AppRuntimeServices 类型作为权威列表。若过程使用了 context.services 中某个服务,而 AppRuntimeServices 中没有对应 Effect 服务,则不要迁移。目标过程不应已经使用 Effect(即没有 from 'effect' 导入)。Stripe 过程只有在能够调用 apps/riptide-api/src/effects/services/stripe/stripe.service.ts 中公开的 Effect StripeService 时才可迁移;不得从迁移后的 oRPC 过程直接调用 Stripe TypeScript SDK。STRIPE_SECRET_KEY 只能通过 Stripe HTTP 适配器中的 Config.redacted 使用,不得打印、检查或穿过程序代码。kv 仍不可用,迁移后的过程没有通用 KvService。
主要能力 技能提供经典 Base 到 Effect Base 的映射关系,例如 apiBaseOrgRequired 对应 effectOrpcBaseOrganizationRequired,apiBasePublic 对应 effectOrpcBasePublic,apiBaseForOrganizationAdmin 对应 effectOrpcBaseForOrganizationAdmin,daemonBase 对应 effectOrpcDaemonBase。给出新文件命名约定,即在原文件旁创建 .effect.ts 后缀文件。提供 Effect 过程代码的基本结构,包括从 runtime 中 yield 服务、使用 PostgresDb 进行查询和事务、用 Effect.fail 返回 oRPC 错误、用 Effect.tapError 记录日志并上报 Sentry、用 Effect.catchTags 或 mapPostgresErrorToResponse 映射 Postgres 错误。还说明如何将经典 logger 调用替换为 Effect.logInfo/logError 并结合 Effect.annotateLogs 添加结构化上下文。若原过程使用计费中间件,需要改用 requiresBillingEffectMiddleware。最后更新 apps/riptide-api/src/orpc/router.ts 中的导入与路由,并在测试通过后删除原文件。
使用方式 流程包括:识别要迁移的过程并理解其 Base、路由路径、输入输出契约、授权要求、数据库操作和错误处理模式;确定对应的 Effect Base;创建 .effect.ts 文件;按模板编写 Effect 过程;处理服务访问、简单查询、事务、错误处理、并行查询、日志等改写模式;添加计费中间件(如需要);更新路由;删除原文件;运行类型检查和质量校验。验证命令为 bun --bun run typecheck --filter @humanlayer/riptide-api 和 bun --bun run quality。不要在本地运行测试,因为 riptide-api 测试依赖 Docker 容器(Postgres、Electric SQL),由 CI 负责验证。
适用场景 适用于已采用 Effect 与 oRPC 的 TypeScript 代码库,并希望按过程逐个进行 Effect 迁移,以保持每次变更可控且易于审查。也适用于需要将数据库访问、事务、错误映射、日志和 Sentry 上报统一到 Effect 模式的场景。
限制 只能迁移那些使用 AppRuntimeServices 中已有 Effect 服务的过程;使用 jira、linear、kv、billingAccess 等没有 Effect 封装的服务的过程不应迁移。Effect 测试使用 @effect/vitest,依赖 Docker 容器,只在 CI 中运行。不得修改该技能文件本身。不得在 Effect 生成器中使用 throw,而应使用 Effect.fail。不要直接访问 context.services.db,而应从 runtime 获取 PostgresDb。不要为每个过程创建新的 runtime/layers,应使用共享 appRuntime。不要混用 async/await 与 Effect 生成器。不要遗漏错误日志与 Sentry 捕获。
参考示例 简单查询示例见 apps/riptide-api/src/orpc/api/hosts/alias-list.effect.ts;带事务和日志的示例见 apps/riptide-api/src/orpc/api/comments/update.effect.ts;带计费和完整错误链的示例见 apps/riptide-api/src/orpc/api/uploads/create.effect.ts;使用 S3 服务的示例见 apps/riptide-api/src/orpc/api/uploads/download-url.effect.ts。