Rails Service Objects

Rails Service Objects Specialist

Specialized in creating clean, testable service objects for complex business workflows.

When to Use This Skill

• Implementing multi-step business processes (e.g., order processing, payment workflows)
• Coordinating operations across multiple models
• Business logic that requires transaction safety
• Complex workflows with multiple success/failure paths
• Operations that need structured result objects

Core Principles

• Single Responsibility: Each service handles one business operation
• Call Interface: Use call method as the primary interface
• Result Objects: Return structured success/failure results
• Transaction Safety: Wrap operations in transactions when needed
• Testability: Easy to test in isolation

Implementation Guidelines

Basic Service Object Structure

# app/services/order_processing_service.rb
class OrderProcessingService
    def initialize(order, options = {})
        @order = order
        @options = options
    end

    def call
        ActiveRecord::Base.transaction do
            validate_order!
            charge_payment
            update_inventory
            send_confirmation
            Result.success(@order)
        end
    rescue => e
        Result.failure(e.message)
    end

    private

    # WHY: Ensure order meets business rules before processing
    def validate_order!
        raise ValidationError unless @order.valid? && @order.items.any?
    end

    def charge_payment
        # Payment processing logic
    end

    def update_inventory
        # Inventory update logic
    end

    def send_confirmation
        # Email notification logic
    end
end

Usage Pattern

# In controller
def create
    service = OrderProcessingService.new(order, payment_method: params[:payment_method])
    result = service.call

    if result.success?
        redirect_to order_path(result.data), notice: 'Order processed successfully'
    else
        redirect_to cart_path, alert: result.error
    end
end

Result Object Pattern

# app/services/result.rb
class Result
    attr_reader :data, :error

    def self.success(data = nil)
        new(success: true, data: data)
    end

    def self.failure(error)
        new(success: false, error: error)
    end

    def initialize(success:, data: nil, error: nil)
        @success = success
        @data = data
        @error = error
    end

    def success?
        @success
    end

    def failure?
        !@success
    end
end

Tools to Use

• Read: Read existing service objects and models
• Write: Create new service object files
• Edit: Modify existing service objects
• Bash: Run tests for service objects
• mcp__serena__find_symbol: Find related models and services

Bash Commands

# Generate service directory (if needed)
mkdir -p app/services

# Run service tests
bundle exec rspec spec/services/order_processing_service_spec.rb

Workflow

1. Understand Requirements: Clarify business logic requirements
2. Write Tests First: Use rails-rspec-testing skill
3. Verify Tests Fail: Confirm tests fail correctly
4. Implement Service: Create service object with clear interface
5. Handle Errors: Implement proper error handling
6. Return Results: Use Result objects for structured responses
7. Run Tests: Ensure all tests pass
8. Run Rubocop: Validate code style

Related Skills

• rails-rspec-testing: For writing service object tests
• rails-transactions: For transaction management within services
• rails-error-handling: For comprehensive error handling
• rails-model-design: For understanding model interfaces

Coding Standards

See Rails Coding Standards

TDD Workflow

Follow TDD Workflow

Key Reminders

• Keep services focused on single business operation
• Always return Result objects for consistent interface
• Use transactions when coordinating multiple models
• Extract complex logic into private methods
• Write tests before implementation (TDD)
• Use English comments explaining WHY