rails-patterns

Rails Patterns

Patrons de framework pour les applications Ruby on Rails modernes (Rails 7.1+ et 8.x). Rails est conçu pour être opinioné ; ces patrons représentent ce sur quoi la communauté s'est accordée pour les applications qui restent maintenables au-delà de la barre des 50 modèles. Ce skill est le « comment ». Pour le « quoi » et le « quand » (les décisions quant au patron à utiliser), consultez les règles des patrons Ruby — rules/ruby/patterns.md dans ce dépôt, installé comme rules/ecc/ruby/patterns.md.

Quand activer

• Construire une application Rails (full-stack, API-only ou hybride)
• Relire une PR qui touche à app/ ou config/
• Générer des modèles, contrôleurs, services ou tâches
• Une action de contrôleur dépasse ~10 lignes
• Un fichier modèle dépasse ~200 lignes
• Des requêtes ActiveRecord apparaissent dans les contrôleurs ou les vues

Concepts fondamentaux

Le contrat de répertoire

Les applications Rails suivent une structure prévisible. Ajoutez des répertoires délibérément, pas à la légère.

app/
  models/         Modèles ActiveRecord. Persistance et logique métier proches des données.
  controllers/    Traitement des requêtes HTTP. Orchestration légère uniquement.
  views/          Templates ERB. Aucune logique métier.
  components/     Classes ViewComponent. Logique de vue qui nécessite des tests.
  services/       Objets service. Opérations métier en plusieurs étapes.
  forms/          Objets formulaire. Gestion complexe de formulaires sur plusieurs modèles.
  queries/        Objets requête. Requêtes ActiveRecord réutilisables et composables.
  jobs/           Tâches d'arrière-plan (asynchrones). Travail asynchrone via Solid Queue, Sidekiq ou GoodJob.
  mailers/        Classes ActionMailer.
  helpers/        Helpers de vue. Logique de présentation minimale uniquement.
  policies/       Politiques d'autorisation (si utilisation de Pundit). Optionnel.
  channels/       Canaux ActionCable pour le travail WebSocket.

Évitez app/lib/, app/utils/, app/managers/. Si quelque chose ne correspond pas aux répertoires ci-dessus, la conception nécessite généralement une refonte, pas un nouveau répertoire. Le code véritablement générique va dans lib/.

Contrôleurs légers

Les contrôleurs reçoivent une requête, délèguent à l'objet approprié et renvoient une réponse. La logique métier vit ailleurs. (Conformément aux règles des patrons Ruby, extrayez dans un objet service lorsque le contrôleur commence à porter plusieurs responsabilités.)

Objets service

Par défaut pour les opérations métier qui touchent plus qu'une simple sauvegarde d'un seul modèle. Conventions pour les garder cohérents :

• Namespace par domaine (Invoices::Create), pas par suffixe (InvoiceCreator).
• Une méthode de classe .call délègue à une instance #call.
• Retourne un objet Result, pas un booléen ou un enregistrement brut, afin que l'appelant puisse bifurquer sur le succès, les erreurs et l'enregistrement concerné.
• Encapsulez les écritures multi-enregistrements dans une transaction.
• Gardez chaque service mono-objectif (Invoices::Create, Invoices::MarkPaid), jamais Invoices::Manager.

Objets formulaire

Lorsqu'un formulaire s'étend sur plusieurs modèles ou a des champs qui ne correspondent pas à des colonnes, utilisez un objet formulaire plutôt que des attributs imbriqués ou des attributs virtuels sur le mauvais modèle. Il se comporte comme un modèle pour la vue (form_with model: @form) tout en composant les enregistrements de manière propre.

Objets requête

Pour les requêtes ActiveRecord réutilisées dans les contrôleurs ou services, ou trop complexes pour un scope, extrayez un objet requête qui accepte un scope en entrée afin qu'il se compose. Règle empirique : un scope qui dépasse trois conditions chaînées ou commence à prendre des paramètres veut devenir un objet requête.

Tâches d'arrière-plan

Déchargez tout ce qui est lent. (Conformément aux règles des patrons Ruby, Solid Queue pour un Rails 8 greenfield avec un débit modeste ; Sidekiq lorsque vous avez besoin d'observabilité mature, d'un débit élevé ou de Redis existant.) Quel que soit l'adaptateur : passez des IDs, pas des enregistrements, rendez perform idempotent et définissez retry_on/discard_on explicitement.

ViewComponent plutôt que les partials

Pour une logique de vue avec un rendu conditionnel, plus de deux arguments ou une réutilisation dans plus de trois endroits, préférez un ViewComponent. Les composants sont testables de manière isolée et exposent leur interface explicitement ; les partials avec une logique conditionnelle profonde deviennent une dette.

Hotwire : Turbo et Stimulus

La pile frontend Rails par défaut. (Conformément aux règles des patrons Ruby, préférez Hotwire pour les applications rendues serveur ; utilisez React/Vue uniquement lorsque la complexité d'interaction justifie la surface client.) Turbo Frames pour les mises à jour partielles de page, Turbo Streams pour les mises à jour pilotées par le serveur, Stimulus pour les petits comportements côté client à côté du balisage.

La pile Solid de Rails 8

Rails 8 apporte des valeurs par défaut basées sur la base de données qui nécessitaient auparavant Redis : Solid Queue (tâches), Solid Cache (cache), Solid Cable (ActionCable). Le compromis est une charge de base de données plus élevée pour un composant d'infrastructure en moins ; un bon choix pour un débit modeste, Redis restant gagnant à grande échelle. Kamal est l'outil de déploiement Docker par défaut.

Exemples de code

Contrôleur léger avec un objet service

# Mauvais : logique métier dans le contrôleur
class InvoicesController < ApplicationController
  def create
    @invoice = Invoice.new(invoice_params)
    @invoice.user = current_user
    @invoice.line_items.build(invoice_params[:line_items])
    @invoice.tax_total = TaxCalculator.new(@invoice).calculate
    @invoice.total = @invoice.line_items.sum(&:amount) + @invoice.tax_total

    if @invoice.save
      InvoiceMailer.created(@invoice).deliver_later
      AccountingExportJob.perform_later(@invoice.id)
      redirect_to @invoice, notice: "Facture créée"
    else
      render :new
    end
  end
end

# Bon : le contrôleur orchestre, le service fait le travail
class InvoicesController < ApplicationController
  def create
    result = Invoices::Create.call(params: invoice_params, user: current_user)

    if result.success?
      redirect_to result.invoice, notice: "Facture créée"
    else
      @invoice = result.invoice
      render :new, status: :unprocessable_entity
    end
  end
end

L'objet service

# app/services/invoices/create.rb
module Invoices
  class Create
    # Struct garde ceci exécutable sur chaque Ruby que Rails 7.1 supporte.
    # Sur Ruby 3.2+, `Data.define(:success?, :invoice, :errors)` est une
    # alternative immuable plus concise.
    Result = Struct.new(:success, :invoice, :errors, keyword_init: true) do
      def success?
        success
      end
    end

    def self.call(params:, user:)
      new(params: params, user: user).call
    end

    def initialize(params:, user:)
      @params = params
      @user = user
    end

    def call
      invoice = build_invoice
      ApplicationRecord.transaction do
        invoice.save!
      end
      begin
        send_notifications(invoice)
      rescue StandardError => e
        Rails.logger.error("Échec de l'envoi de notification pour la facture #{invoice.id} : #{e.message}")
      end
      Result.new(success: true, invoice: invoice, errors: nil)
    rescue ActiveRecord::RecordInvalid => e
      Result.new(success: false, invoice: e.record, errors: e.record.errors)
    end

    private

    attr_reader :params, :user

    def build_invoice
      invoice = user.invoices.new(params.except(:line_items))
      invoice.line_items.build(params[:line_items])
      invoice.tax_total = TaxCalculator.call(invoice)
      invoice.total = invoice.line_items.sum(&:amount) + invoice.tax_total
      invoice
    end

    def send_notifications(invoice)
      InvoiceMailer.created(invoice).deliver_later
      AccountingExportJob.perform_later(invoice.id)
    end
  end
end

Objet formulaire

# app/forms/signup_form.rb
class SignupForm
  include ActiveModel::Model
  include ActiveModel::Attributes

  attribute :email, :string
  attribute :password, :string
  attribute :company_name, :string
  attribute :terms_accepted, :boolean

  validates :email, presence: true, format: URI::MailTo::EMAIL_REGEXP
  validates :password, presence: true, length: { minimum: 12 }
  validates :company_name, presence: true
  validates :terms_accepted, acceptance: true

  attr_reader :user, :company

  def save
    return false unless valid?

    ApplicationRecord.transaction do
      @company = Company.create!(name: company_name)
      @user = @company.users.create!(email: email, password: password, role: :owner)
    end
    true
  rescue ActiveRecord::RecordInvalid => e
    errors.merge!(e.record.errors)
    false
  end
end

Objet requête

# app/queries/invoices/overdue.rb
module Invoices
  class Overdue
    def self.call(scope: Invoice.all, as_of: Time.current)
      new(scope: scope, as_of: as_of).call
    end

    def initialize(scope:, as_of:)
      @scope = scope
      @as_of = as_of
    end

    def call
      scope
        .where(status: :sent)
        .where(due_date: ..as_of)
        .where.not(id: paid_invoice_ids)
        .includes(:customer, :line_items)
    end

    private

    attr_reader :scope, :as_of

    def paid_invoice_ids
      Payment.where(created_at: ..as_of).pluck(:invoice_id)
    end
  end
end

Les objets requête acceptent un scope, donc ils se composent : Invoices::Overdue.call(scope: current_user.invoices).

Prévention N+1

# Mauvais : N+1 dans la vue lorsqu'elle appelle post.author.name
@posts = Post.published

# Bon : chargement eager
@posts = Post.published.includes(:author)

includes laisse Rails choisir entre preload et eager_load. Forcez preload pour des requêtes séparées, eager_load pour un JOIN lors du filtrage sur l'association. Depuis Rails 6.1, strict_loading lève une erreur en cas de chargement paresseux accidentel.

Cache de compteur

class Comment < ApplicationRecord
  belongs_to :post, counter_cache: true
end

add_column :posts, :comments_count, :integer, default: 0, null: false

post.comments_count devient une lecture de colonne au lieu d'un COUNT(*). Cet exemple suppose une nouvelle table ; ajouter un cache de compteur à une table qui a déjà des lignes nécessite un backfill, qui est hors de portée ici.

Forme de la tâche d'arrière-plan

Passez les IDs des enregistrements, pas les enregistrements. Les tentatives rendent la livraison au moins une fois, donc toute tâche qui appelle un service externe doit être idempotente — sinon un échec transitoire après que l'appel distant a réussi dupliquera l'effet lors de la tentative suivante.

class AccountingExportJob < ApplicationJob
  queue_as :exports

  retry_on AccountingApi::TransientError, wait: :polynomially_longer, attempts: 5
  discard_on AccountingApi::PermanentError

  def perform(invoice_id)
    invoice = Invoice.find(invoice_id)
    export = AccountingExport.create_or_find_by!(
      invoice: invoice,
      idempotency_key: "invoice-export-#{invoice.id}-#{invoice.updated_at.to_i}"
    )
    return if export.completed_at?

    receipt = AccountingApi.export(invoice, idempotency_key: export.idempotency_key)
    export.update!(completed_at: Time.current, external_id: receipt.id)
  end
end

add_index :accounting_exports, :idempotency_key, unique: true

L'index unique est ce qui rend cela sûr : lorsque deux tentatives se précipitent, la base de données rejette la deuxième insertion et Active Record résout le conflit dans l'appel, retournant la ligne existante. Cela se produit sans aucune tentative au niveau de la tâche — retry_on ci-dessus ne couvre que AccountingApi::TransientError. La garde couvre la fenêtre avant l'appel distant ; passer idempotency_key à l'API couvre la fenêtre après, donc un crash entre l'appel API et update! se résout toujours en un seul export.

ViewComponent

# app/components/invoice_status_badge_component.rb
class InvoiceStatusBadgeComponent < ViewComponent::Base
  STATUS_CLASSES = {
    draft: "bg-gray-100 text-gray-800",
    sent: "bg-blue-100 text-blue-800",
    paid: "bg-green-100 text-green-800",
    overdue: "bg-red-100 text-red-800"
  }.freeze

  def initialize(invoice:)
    @invoice = invoice
  end

  def call
    tag.span(@invoice.status.humanize, class: "rounded-full px-2 py-1 text-sm #{status_class}")
  end

  private

  def status_class
    STATUS_CLASSES.fetch(@invoice.status.to_sym, "bg-gray-100")
  end
end

<%= render InvoiceStatusBadgeComponent.new(invoice: @invoice) %>

Hotwire

<%# Turbo Frame : cliquer sur Modifier remplace uniquement ce frame %>
<%= turbo_frame_tag "invoice_#{@invoice.id}" do %>
  <div class="invoice">
    <%= link_to "Modifier", edit_invoice_path(@invoice) %>
  </div>
<% end %>

<%# Turbo Stream : app/views/comments/create.turbo_stream.erb %>
<%= turbo_stream.append "comments", @comment %>
<%= turbo_stream.update "comment_form", partial: "form", locals: { comment: Comment.new } %>

// app/javascript/controllers/copy_to_clipboard_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["source"]

  copy() {
    navigator.clipboard.writeText(this.sourceTarget.value)
  }
}

Callbacks acceptables vs inacceptables

# Acceptable : normalisation pure des données
class User < ApplicationRecord
  before_validation :normalize_email

  private

  def normalize_email
    self.email = email.to_s.downcase.strip
  end
end

# À déplacer vers un service à la place : effets de bord cachés dans un callback
# class User < ApplicationRecord
#   after_create :send_welcome_email  # difficile à désactiver, difficile à tester
# end

Bon concern vs mauvais concern

# Bon : véritablement transversal, réutilisable entre modèles non liés
# app/models/concerns/soft_deletable.rb
module SoftDeletable
  extend ActiveSupport::Concern

  included do
    scope :active, -> { where(deleted_at: nil) }
    scope :deleted, -> { where.not(deleted_at: nil) }
  end

  def soft_delete! = update!(deleted_at: Time.current)
  def restore! = update!(deleted_at: nil)
end

# Mauvais : un "concern" utilisé par exactement un modèle, contenant une logique qui lui appartient
# app/models/concerns/invoice_calculations.rb
module InvoiceCalculations
  extend ActiveSupport::Concern

  def calculate_total
    line_items.sum(&:amount) + tax_total
  end
end
# Seulement Invoice inclut cela. Ce n'est pas transversal ; c'est la propre logique d'Invoice
# cachée dans un module pour l'apparence d'un modèle "léger". Remettez-le dans Invoice.

Un concern utilisé par une seule classe n'est que du déplacement de code ; il appartient à cette classe. Un concern devrait encapsuler un comportement partagé par au moins deux modèles non liés. Si vous ne pouvez pas nommer le concern sans un nom de modèle, il n'est pas vraiment transversal.