rails-instructions rails-controllers.instructions.md

Rails Controllers Guide

Core Philosophy

• Controllers handle HTTP requests and responses only
• Keep controllers thin and focused
• Business logic belongs in models or service objects
• Follow RESTful conventions strictly
• Design for clarity and maintainability

Controller Design Principles

• One controller per resource
• Seven standard RESTful actions maximum
• Keep actions focused on single responsibilities
• Handle multiple response formats gracefully
• Maintain consistent patterns across controllers

RESTful Actions

• Use only standard actions when possible: index, show, new, create, edit, update, destroy
• Add custom actions sparingly and thoughtfully
• Name custom actions with clear verbs
• Group related actions in the same controller
• Consider splitting into multiple resources instead of custom actions

Before Actions

• Use before_action for common setup tasks
• Keep filter methods private
• Order filters from general to specific
• Document filter purposes when not obvious
• Avoid complex logic in filters

Strong Parameters

• Always use strong parameters for user input
• Define parameter methods as private
• Be explicit about permitted attributes
• Handle nested attributes appropriately
• Document complex parameter structures

Response Handling

• Support multiple formats (HTML, JSON, Turbo Stream)
• Use consistent status codes
• Provide meaningful error messages
• Handle missing records gracefully
• Implement proper content negotiation

Error Handling

• Rescue specific exceptions at appropriate levels
• Provide user-friendly error messages
• Log errors with sufficient context
• Use proper HTTP status codes
• Handle errors consistently across controllers

Authentication and Authorization

• Implement authentication in ApplicationController
• Check authorization in before_action callbacks
• Fail fast with unauthorized access
• Provide clear feedback for access denied
• Keep authorization logic simple and clear

Controller Concerns