Service Agent 是一个 Rails 服务对象开发助手技能,来源为 thibautbaissac/rails_ai_agents 项目的 service-agent 技能包。它的目标是在 Rails 应用中创建结构清晰、可测试、易维护的业务服务对象,并遵循 SOLID 原则。
用途 该技能用于在开发者编写或重构 Rails 业务逻辑时,按统一约定生成服务对象及其配套测试。它特别强调将业务逻辑从控制器和模型中抽离,通过服务对象承载跨模型逻辑、事务操作以及带有副作用的动作,并支持在控制器、后台任务或控制台中被复用。
主要能力 技能内部将角色设定为服务对象、命令模式与 SOLID 原则方面的专家,并明确了以下做法:始终同步编写 RSpec 测试、遵循单一职责原则、使用 Result 对象处理成功与失败。它还规定了应用分层边界:负责创建与修改 app/services 下的业务服务,读取 app/models 中的 ActiveRecord 模型,读取并调用 app/queries 中的查询对象、app/validators 中的自定义校验器、app/mailers 中的邮件类,读取 app/jobs 并可将任务入队;同时负责创建与修改 spec/services,读取与修改 spec/factories。
结构约定 技能提供了 ApplicationService 基类示例:通过 self.call(...) 转发到实例的 call 方法,并提供 success 与 failure 两个私有方法返回统一的 Result 对象。Result 使用 Ruby 3.2+ 的 Data.define 定义不可变结构,包含 success、data、error 字段,以及 success? 与 failure? 判定方法。服务类示例采用模块命名空间(如 Entities::CreateService),构造函数接收关键字参数(如 user:、params:),call 方法中先做授权判断,再构建实体、保存、触发副作用并返回成功或失败结果。
服务模式 技能归纳了四种覆盖常见场景的模式:简单 CRUD 服务(守卫子句、保存、副作用)、带事务的服务(ActiveRecord::Base.transaction 与特定异常捕获)、计算/查询服务(记忆化、聚合查询、update_columns)、带注入依赖的服务(默认通知器模式以提升可测试性)。
测试与使用方式 测试方面,技能要求覆盖标准创建服务(合法参数、非法参数、授权失败)、使用 receive(:call) 断言测试副作用、以及测试支付或记录失败时的事务回滚;约定用 subject(:result) 表示服务调用结果,按场景使用 context 分组,并同时断言成功/失败状态以及 data/error 值。在控制器中的使用方式为调用 Services::XxxService.call 并根据 result.success? 决定重定向或渲染错误。
适用场景与限制 技能说明,当逻辑涉及多个模型、需要事务、存在副作用(邮件、通知、外部 API)、逻辑过于复杂不适合放在模型中,或需要复用逻辑时适合使用服务对象;而对于没有业务逻辑的简单 CRUD、逻辑明显属于模型、或仅为包装而无附加价值的服务,则不建议使用。
技能中给出的可执行命令包括:运行全部服务测试 bundle exec rspec spec/services/、运行指定服务测试 bundle exec rspec spec/services/entities/create_service_spec.rb、运行指定行 bundle exec rspec spec/services/entities/create_service_spec.rb:25、输出详细文档格式 bundle exec rspec --format documentation spec/services/、对服务执行 lint bundle exec rubocop -a app/services/、对规格执行 lint bundle exec rubocop -a spec/services/,以及通过 bin/rails console 手动测试服务。
边界要求为:始终编写服务规格、使用 Result 对象、遵循 SRP;在修改已有服务或添加外部 API 调用前需要先询问;绝不跳过测试、绝不把服务逻辑放进控制器或模型、绝不忽略错误处理。关于价格、收费方式、平台支持范围等信息,资料中暂未提供。