Copilot instructions

1---
2description: Rails Service Objects Guide
3applyTo: "app/services/**/*.rb"
4---
5 
6# Rails Service Objects Guide
7 
8## Core Philosophy
9 
10- Service objects encapsulate complex business operations
11- Keep services focused on single responsibilities
12- Make services easy to test and understand
13- Use services to keep models and controllers thin
14- Design for reusability and composability
15 
16## When to Use Service Objects
17 
18- Complex operations spanning multiple models
19- External API integrations
20- Multi-step processes with transactions
21- Business logic that doesn't fit naturally in models
22- Operations requiring detailed error handling
23- Background job processing logic
24 
25## Service Design Principles
26 
27- One service, one responsibility
28- Clear, descriptive naming that explains the operation
29- Consistent interface across services
30- Explicit dependencies and parameters
31- Predictable return values and error handling
32 
33## Naming Conventions
34 
35- Use verb-based names that describe the action
36- Include the domain context in the name
37- Examples: `UserRegistrationService`, `PaymentProcessor`, `OrderFulfillment`
38- Keep names specific and intention-revealing
39- Avoid generic names like `UserService`
40 
41## Service Structure
42 
43- Include ActiveModel modules for validations when needed
44- Define clear public interface
45- Keep implementation details private
46- Use dependency injection for testability
47- Document complex logic thoroughly
48 
49## Input Handling
50 
51- Validate inputs early and clearly
52- Use ActiveModel::Attributes for parameter handling
53- Define explicit attribute types
54- Provide meaningful validation messages
55- Handle optional parameters gracefully
56 
57## Return Values
58 
59- Return consistent, predictable results
60- Use success/failure pattern for operations
61- Include relevant data in responses
62- Provide clear error information
63- Consider using Result objects for complex returns
64 
65## Error Handling
66 
67- Anticipate and handle expected failures
68- Use exceptions for unexpected errors
69- Provide actionable error messages
70- Log errors with appropriate context
71- Design for graceful degradation
72 
73## Transaction Management
74 
75- Wrap related database changes in transactions
76- Handle rollbacks appropriately
77- Keep transactions as short as possible
78- Document transaction boundaries
79- Test rollback scenarios
80 
81## Testing Service Objects
82 
83- Test services in isolation
84- Mock external dependencies
85- Verify success and failure paths
86- Test edge cases thoroughly
87- Ensure idempotency where appropriate
88 
89## Dependency Injection
90 
91- Inject dependencies through initialization
92- Avoid hard-coded dependencies
93- Use interfaces for external services
94- Keep services loosely coupled
95- Document required dependencies
96 
97## Service Composition
98 
99- Build complex operations from simple services
100- Keep services composable and reusable
101- Avoid service objects calling other services directly
102- Use orchestrator services for complex workflows
103- Maintain clear boundaries between services
104 
105## Background Job Integration
106 
107- Design services to work synchronously and asynchronously
108- Keep job classes thin, delegate to services
109- Handle job failures gracefully
110- Make services idempotent for retries
111- Log job execution appropriately
112 
113## External API Integration
114 
115- Isolate API logic in dedicated services
116- Handle API failures gracefully
117- Implement appropriate retry logic
118- Cache API responses when sensible
119- Monitor API usage and errors
120 
121## Performance Considerations
122 
123- Profile service execution time
124- Optimize database queries
125- Consider caching expensive operations
126- Batch operations when possible
127- Monitor resource usage
128 
129## Service Organization
130 
131- Group related services in modules
132- Keep service files in app/services
133- Organize by domain or feature
134- Maintain consistent file structure
135- Document service relationships
136 
137## Common Patterns
138 
139- Form objects for complex input handling
140- Query objects for complex database queries
141- Presenter objects for view logic
142- Policy objects for authorization rules
143- Workflow objects for multi-step processes
144 
145## Anti-Patterns to Avoid
146 
147- God services that do too much
148- Services that mirror controller actions
149- Anemic services with no real logic
150- Services tightly coupled to specific views
151- Services that bypass model validations
152 
153## Refactoring to Services
154 
155- Extract complex model methods
156- Move controller logic to services
157- Consolidate scattered business logic
158- Simplify fat models
159- Improve testability
160 
161## Documentation Standards
162 
163- Document service purpose clearly
164- Explain complex business rules
165- Provide usage examples
166- Note performance considerations
167- Include error handling details
168 
169## Integration Guidelines
170 
171- Call services from controllers
172- Use services in background jobs
173- Compose services for complex operations
174- Keep services framework-agnostic when possible
175- Design for future API exposure
176 
177## Best Practices Summary
178 
179- Keep services focused and single-purpose
180- Make dependencies explicit
181- Handle errors gracefully
182- Write comprehensive tests
183- Design for reusability
184 
185Remember: Service objects are about organizing complex business logic. Keep them focused, testable, and easy to understand.
186