Skip to content

skillBackend and APIsrubyrails

Rails Service Objects

Extracts business logic out of fat Rails controllers and models into small service and query objects, with specs that prove behavior stays the same.

npx workspacetemplates add rails-service-objects --tool claude-code

Writes 1 file to .claude/skills/rails-service-objects/

.claude/skills/rails-service-objects/SKILL.md29 lines · 1.7 KBFile
---
name: rails-service-objects
description: Extracts business logic out of fat Rails controllers and models into small service and query objects, with specs that prove behavior stays the same.
---

# Rails service objects

Extract only when it makes a flow easier to test. Do not wrap a one-line `save` in a class.

## Steps

1. Pick one fat action or callback. Read it with its model, routes and existing specs. Write the list of side effects it performs, in order.
2. If no spec covers it, write a request spec or model spec for the current behavior first and run it green.
3. Create `app/services/<verb>_<noun>.rb`, for example `PlaceOrder`. One public method, `call`, plus a class method `self.call(...)` that delegates to it. Pass plain arguments, not the controller or params object.
4. Return a result object (`Result.new(success?, record, errors)`) instead of raising for expected failures. Raise only for bugs.
5. Move callbacks that cause side effects (mail, webhooks, charges) into the service. Keep validations and data integrity in the model.
6. For a growing chain of `where` and `joins`, create a query object in `app/queries` that takes a relation and returns a relation, so it can be chained.
7. The controller now parses params, calls the service, and renders by result.

## Rules

- Wrap multi-record writes in `ActiveRecord::Base.transaction` and enqueue jobs after commit.
- Never let a service call another service through a hidden global; pass collaborators as arguments.
- Services must not render, redirect or read `current_user` implicitly.
- Run `bundle exec rspec` after every extraction.

## Report

Name each new class, the lines removed from the old location, and the spec that proves behavior is unchanged.

What it does

A Rails controller action that creates a record, charges a card, sends mail and enqueues a job is hard to test and harder to change. This skill moves that sequence into a plain Ruby object with one public method and a clear result.

It also pulls tangled scopes and joins into query objects. Each extraction is small, covered by a spec first, and leaves the callers easier to read.

Example

you › Refactor OrdersController#create, it does too much.

agent › Extracted `PlaceOrder` (app/services/place_order.rb) covering stock check, payment and confirmation mail. The controller dropped from 41 lines to 12. Moved the after_create mailer callback into the service and enqueued it after commit. Added spec/services/place_order_spec.rb; the existing request spec still passes.

Questions

Is a service object always the right fix?
No. A long method with one responsibility can simply be split into private methods. The skill extracts only flows with several steps or side effects.
Why a result object instead of exceptions?
A declined card is a normal outcome, not a bug. A result lets the controller branch without rescue blocks.
  • API Error Responses

    SkillBackend and APIs

    Free
  • API Pagination Design

    SkillBackend and APIs

    Free
  • API Versioning Strategy

    SkillBackend and APIs

    Free
  • Background Job Design

    SkillBackend and APIs

    Free