Rails Service Object Patterns

Analyze and recommend patterns for extracting and organizing business logic in Rails applications.

Quick Reference

Supporting Documentation

• patterns.md - Result objects, form objects, and profile-aware guidance

Core Principles

1. VerbNoun naming: CreateOrder, SendInvitation -- never OrderService or UserManager
2. One public method: Expose only call (or perform)
3. Explicit return values: Use Result objects, never exceptions for expected flow control
4. Profile-aware extraction: See "When to Extract" below

When to Extract a Service (Profile-Dependent)

Omakase: Only extract to a service when the workflow genuinely spans multiple unrelated models or external systems. Prefer concerns and enriched model methods.

Service-oriented / API-first: Service objects are the default extraction target for any non-trivial business logic.

Result Object Pattern

Use Struct.new(keyword_init: true) for lightweight results. Never raise exceptions for expected failures (validation, auth, payment decline).

class AuthenticateUser
  Result = Struct.new(:success?, :user, :error, keyword_init: true)

  def initialize(email:, password:)
    @email = email
    @password = password
  end

  def call
    user = User.find_by(email: @email)
    if user&.authenticate(@password)
      Result.new(success?: true, user: user)
    else
      Result.new(success?: false, error: "Invalid credentials")
    end
  end
end

See patterns.md for the enhanced monad-like ServiceResult with on_success/on_failure chaining.

Anti-Patterns

Output Format

When analyzing or creating services, provide:

1. Service file in app/services/ with VerbNoun naming
2. Result struct if callers need success/failure status
3. Controller integration showing how to call and handle results
4. Test outline covering happy path, failure cases, and edge cases
5. Error handling strategy (Result objects for expected failures, exceptions for unexpected)