Padrões Rails

Padrões de framework para aplicações Ruby on Rails modernas (Rails 7.1+ e 8.x). Rails é opinativo por design; estes são os padrões em que a comunidade convergiu para aplicações que permanecem manteníveis após a marca de 50 modelos. Essa habilidade é o "como". Para o "o quê" e o "quando" (as decisões sobre qual padrão usar), veja as regras de padrões Ruby — rules/ruby/patterns.md neste repositório, instalado como rules/ecc/ruby/patterns.md.

Quando Ativar

• Construindo uma aplicação Rails (full-stack, apenas API ou híbrida)
• Revisando um PR que toca app/ ou config/
• Gerando models, controllers, services ou jobs
• Uma ação de controller cresce além de ~10 linhas
• Um arquivo de model cresce além de ~200 linhas
• Consultas ActiveRecord começam a aparecer em controllers ou views

Conceitos Principais

O contrato de diretório

Aplicações Rails seguem uma estrutura previsível. Adicione diretórios deliberadamente, não casualmente.

app/
  models/         ActiveRecord models. Persistence and domain logic close to the data.
  controllers/    HTTP request handling. Thin orchestration only.
  views/          ERB templates. No business logic.
  components/     ViewComponent classes. View logic that needs tests.
  services/       Service objects. Multi-step business operations.
  forms/          Form objects. Complex form handling across multiple models.
  queries/        Query objects. Reusable, composable ActiveRecord queries.
  jobs/           Background jobs. Async work via Solid Queue, Sidekiq, or GoodJob.
  mailers/        ActionMailer classes.
  helpers/        View helpers. Tiny presentational logic only.
  policies/       Authorization policies (if using Pundit). Optional.
  channels/       ActionCable channels for WebSocket work.

Evite app/lib/, app/utils/, app/managers/. Se algo não se encaixa nos diretórios acima, o design geralmente precisa ser repensado, não um novo diretório. Código verdadeiramente genérico vai para lib/.

Controllers "magros" (skinny controllers)

Controllers recebem uma requisição, delegam para o objeto correto e renderizam uma resposta. A lógica de negócio vive em outro lugar. (De acordo com as regras de padrões Ruby, extraia para um objeto de serviço quando o controller começar a carregar múltiplas responsabilidades.)

Objetos de serviço (Service objects)

O padrão para operações de negócio que tocam mais de um save de model. Convenções que os mantêm consistentes:

• Agrupe por domínio (Invoices::Create), não por sufixo (InvoiceCreator).
• Um método de classe .call delega para uma instância #call.
• Retorne um objeto Result, não um booleano ou um registro puro, para que o chamador possa ramificar em sucesso, erros e o registro afetado.
• Envolva escritas de múltiplos registros em uma transação.
• Mantenha cada serviço com um único propósito (Invoices::Create, Invoices::MarkPaid), nunca Invoices::Manager.

Objetos de formulário (Form objects)

Quando um formulário abrange múltiplos modelos ou tem campos que não mapeiam para colunas, use um objeto de formulário em vez de atributos aninhados ou atributos virtuais no modelo errado. Ele se comporta como um model para a view (form_with model: @form) enquanto compõe registros de forma limpa.

Objetos de consulta (Query objects)

Para consultas ActiveRecord reutilizadas em controllers ou services, ou muito complexas para um escopo, extraia um objeto de consulta que aceita um escopo como entrada para que ele se componha. Regra geral: um escopo que cresce além de três condições encadeadas ou começa a aceitar parâmetros deve se tornar um objeto de consulta.

Jobs em background

Descarregue qualquer coisa lenta. (De acordo com as regras de padrões Ruby, Solid Queue para novas aplicações Rails 8 com throughput modesto; Sidekiq quando você precisar de observabilidade madura, alto throughput ou Redis existente.) Independentemente do adaptador: passe IDs em vez de registros, torne perform idempotente e defina retry_on/discard_on explicitamente.

ViewComponent em vez de parciais

Para lógica de visualização com renderização condicional, mais de dois argumentos ou reutilização em mais de três lugares, prefira um ViewComponent. Componentes são testáveis isoladamente e expõem sua interface explicitamente; parciais com lógica condicional profunda se tornam dívida técnica.

Hotwire: Turbo e Stimulus

A pilha frontend padrão do Rails. (De acordo com as regras de padrões Ruby, prefira Hotwire para aplicações renderizadas no servidor; use React/Vue apenas quando a complexidade da interação justificar a superfície do cliente.) Turbo Frames para atualizações parciais de página, Turbo Streams para atualizações controladas pelo servidor, Stimulus para pequenos comportamentos no lado do cliente adjacentes ao markup.

A pilha Solid do Rails 8

…