rails-instructions rails-services.instructions.md

Rails Service Objects Guide

Core Philosophy

• Service objects encapsulate complex business operations
• Keep services focused on single responsibilities
• Make services easy to test and understand
• Use services to keep models and controllers thin
• Design for reusability and composability

When to Use Service Objects

• Complex operations spanning multiple models
• External API integrations
• Multi-step processes with transactions
• Business logic that doesn't fit naturally in models
• Operations requiring detailed error handling
• Background job processing logic

Service Design Principles

• One service, one responsibility
• Clear, descriptive naming that explains the operation
• Consistent interface across services
• Explicit dependencies and parameters
• Predictable return values and error handling

Naming Conventions

• Use verb-based names that describe the action
• Include the domain context in the name
• Examples: UserRegistrationService, PaymentProcessor, OrderFulfillment
• Keep names specific and intention-revealing
• Avoid generic names like UserService

Service Structure

• Include ActiveModel modules for validations when needed
• Define clear public interface
• Keep implementation details private
• Use dependency injection for testability
• Document complex logic thoroughly

Input Handling

• Validate inputs early and clearly
• Use ActiveModel::Attributes for parameter handling
• Define explicit attribute types
• Provide meaningful validation messages
• Handle optional parameters gracefully

Return Values

• Return consistent, predictable results
• Use success/failure pattern for operations
• Include relevant data in responses
• Provide clear error information
• Consider using Result objects for complex returns

Error Handling

• Anticipate and handle expected failures
• Use exceptions for unexpected errors
• Provide actionable error messages
• Log errors with appropriate context
• Design for graceful degradation

Transaction Management