SuperAPI AI 工具集

create-service-object

编程与开发

查看项目

更新于 10-15 22:17

技能介绍

用途:在 Ruby 项目中创建或重构服务类,统一采用 self.call(...) 调用 new(...).call 的入口模式,并返回 { success: …, response: … } 结构的结果契约。

主要能力与流程:

  1. 测试门禁(HARD-GATE):每个服务对象必须先写好并验证测试,再实现。步骤为:先写 .call 的 spec/test(覆盖成功、错误、边界场景),运行并确认因服务尚不存在而失败,然后才写实现;最终产物须包含测试命令与实现前的失败信息。若无法执行,须报告门禁受阻,不能以预期输出代替实际观察到的失败。
  2. 写规格:测试文件放在 spec/services/<module_name>/<service_name>_spec.rb(或 test/services/)。新服务若无既定结果约定,断言 success: 与 response: 顶层键;已有服务沿用其公开结果结构。
  3. 建骨架:在 services/<module_name>/<service_name>.rb 建立正确模块命名空间。
  4. 选模式:标准、批量、纯类方法(Pattern 3)、编排器之一。若不需要实例状态,用 Pattern 3(无 initialize、无实例变量)。
  5. 实现契约:实现 self.call 与 #call;新服务默认用 { success: true, response: { ... } } 或 { success: false, response: { error: { message: '...' } } }。call 不超过 20 行,超出则拆分子服务;输入校验放在 call 顶部,无效则返回错误哈希;只返回序列化数据,不返回原始持久化模型对象。
  6. 错误与日志:只捕获本服务可恢复的领域/传输错误,转换为既定错误结果并记录一次日志;意外缺陷向上传播,以保证监控、事务回滚与任务重试;公开消息不暴露敏感异常细节。
  7. YARD 文档:为 self.call 及所有公开方法添加 @param、类型正确的 @return 与 @raise;self.call 与 #call 分别记录。Pattern 3 若返回非标准结构(如 nil/错误字符串),须在 YARD 与 README 中明确说明。
  8. 模块 README:生成 services/<module_name>/README.md 说明领域上下文,单服务模块也必须编写。

额外约束:事务只包裹必须原子化的多步数据库操作;单一职责,不涉及 HTTP/UI;动态查询须做 SQL 参数净化;共享逻辑抽为纯类方法服务。

扩展资源(按需加载):assets/examples.md(四种模式示例)、assets/service_skeleton.md(起始骨架)、assets/module_readme_template.md(README 模板)。

集成:可与 write-yard-docs、integrate-api-client、implement-calculator-pattern、write-tests、refactor-process 等技能串联。

限制:未提供具体依赖版本、安装命令、支持的 Ruby 框架范围与收费信息;强制执行测试门禁需要可运行测试环境。