用途:code-structure 用于解决业务代码中操作逻辑重复、行为不一致、同一缺陷在多个路径修复不完整的问题,帮助划分编排层(Actions)与共享机制层(Services)的职责。
主要能力:
- 两层分离。Actions 负责业务规则、状态流转、认证与归属校验、失败分类、重试与面向用户的错误;Services 负责可复用操作、provider/SDK 交互、命令执行细节、健康检查/就绪检查,并返回结构化结果。
- 判断准则:涉及“这个产品流程意味着什么”的逻辑留在 actions;涉及“如何可靠地完成这个操作”的逻辑移入 service 层。
- 服务函数设计:按能力块拆分,而非单一巨型方法,例如 createManagedSandbox、prepareRepo、detectPackageManager、installDependencies、runBuildCommand、startSandboxRuntime。每个函数以显式参数接收所需数据,返回结构化输出(如 { ready, previewUrl, proxyPort }),并通过类型化结果或文档化异常显式表达失败。
- 迁移流程:先抽取一个块、替换一个调用方、验证后再迁移其余调用方,保持认证、状态转换、错误处理与事务行为不变,最后运行 typecheck、lint 并确认所有流程正常。
- 反模式提示:巨型 service、隐藏状态变更或事务归属不清的泄漏式 service、参数风格与错误语义不一致的 API、以及没有复用/可测试性/边界收益的过度抽象。
使用方式:资料未提供安装命令或具体调用步骤,暂未提供。技能内容以架构准则、设计原则表、迁移清单和一个邮件服务示例给出,示例中 emailService.ts 提供共享机制,userSignup.ts 与 adminInvite.ts 分别承担编排职责。
适用场景:多个调用方需要同一底层操作(沙箱创建、发送邮件、支付处理);在 action 文件之间复制粘贴操作逻辑;一个工作流中的缺陷修复无法传导到其他相同逻辑;新增功能与现有流程共享机制;或单个调用方因测试、provider 隔离、事务或复杂逻辑需要明确边界时。
限制:避免引入没有具体收益的间接层;若项目已有领域服务、仓储、事务边界与框架模式,应遵循既有边界而非另建分层。