Колбэки Active Record

Это руководство научит вас вмешиваться в жизненный цикл ваших объектов Active Record.

После прочтения этого руководства вы узнаете:

• Когда определенные события случаются в течение жизни объекта Active Record
• Как создавать методы колбэков, отвечающих на события в жизненном цикле объекта
• Как создавать специальные классы, инкапсулирующих обычное поведение для ваших колбэков

1. Жизненный цикл объекта

В результате обычных операций приложения на Rails, объекты могут быть созданы, обновлены и уничтожены. Active Record дает возможность вмешаться в этот жизненный цикл объекта, таким образом, вы можете контролировать свое приложение и его данные.

Валидации позволяют вам быть уверенными, что только валидные данные хранятся в вашей базе данных. Колбэки позволяют вам переключать логику до или после изменения состояния объекта.

class Baby < ApplicationRecord
  after_create -> { puts "Congratulations!" }
end

irb> @baby = Baby.create
Congratulations!

Вы увидите, что есть множество событий жизненного цикла, и вы сможете вклиниться в любое из них, до, после или даже вокруг них.

2. Обзор колбэков

Колбэки это методы, которые вызываются в определенные моменты жизненного цикла объекта. С колбэками возможно написать код, который будет запущен, когда объект Active Record создается, сохраняется, обновляется, удаляется, проходит валидацию или загружается из базы данных.

2.1. Регистрация колбэков

Для того, чтобы использовать доступные колбэки, их нужно зарегистрировать. Можно реализовать колбэки как обычные методы, а затем использовать макро-методы класса для их регистрации в качестве колбэков.

class User < ApplicationRecord
  validates :login, :email, presence: true

  before_validation :ensure_login_has_a_value

  private
    def ensure_login_has_a_value
      if login.blank?
        self.login = email unless email.blank?
      end
    end
end

Макро-методы класса также могут получать блок. Их следует использовать, если код внутри блока такой короткий, что помещается в одну строчку.

class User < ApplicationRecord
  validates :login, :email, presence: true

  before_create do
    self.name = login.capitalize if name.blank?
  end
end

Альтернативно можно передать в колбэк proc, который будут выполнен.

class User < ApplicationRecord
  before_create ->(user) { user.name = user.login.capitalize if user.name.blank? }
end

Наконец, можно определить собственный объект колбэка, который мы раскроем подробнее ниже.

class User < ApplicationRecord
  before_create MaybeAddName
end

class MaybeAddName
  def self.before_create(record)
    if record.name.blank?
      record.name = record.login.capitalize
    end
  end
end

Колбэки также могут быть зарегистрированы на выполнение только при определенных событиях жизненного цикла, что позволяет полностью контролировать в каком контексте ваши колбэки выполняются.

class User < ApplicationRecord
  before_validation :normalize_name, on: :create

  # :on также принимает массив
  after_validation :set_location, on: [ :create, :update ]

  private
    def normalize_name
      self.name = name.downcase.titleize
    end

    def set_location
      self.location = LocationService.query(self)
    end
end

Считается хорошей практикой объявлять методы колбэков как private. Если их оставить public, они могут быть вызваны извне модели и нарушить принципы инкапсуляции объекта.

3. Доступные колбэки

Вот список всех доступных колбэков Active Record, перечисленных в том порядке, в котором они вызываются в течение соответствующих операций:

3.1. Создание объекта

• before_validation
• after_validation
• before_save
• around_save
• before_create
• around_create
• after_create
• after_save
• after_commit / after_rollback

3.2. Обновление объекта

• before_validation
• after_validation
• before_save
• around_save
• before_update
• around_update
• after_update
• after_save
• after_commit / after_rollback

3.3. Уничтожение объекта

• before_destroy
• around_destroy
• after_destroy
• after_commit / after_rollback

3.4. after_initialize и after_find

Всякий раз, когда возникает объект Active Record, будет вызван колбэк after_initialize, или непосредственно при использовании new, или когда запись загружается из базы данных. Он может быть полезен, чтобы избежать необходимости напрямую переопределять метод Active Record initialize.

При загрузке записи из базы данных, будет вызван колбэк after_find. after_find вызывается перед after_initialize, если они оба определены.

Они могут быть зарегистрированы подобно другим колбэкам Active Record.

class User < ApplicationRecord
  after_initialize do |user|
    puts "You have initialized an object!"
  end

  after_find do |user|
    puts "You have found an object!"
  end
end

irb> User.new
You have initialized an object!
=> #<User id: nil>

irb> User.first
You have found an object!
You have initialized an object!
=> #<User id: 1>

3.5. after_touch

Колбэк after_touch будет вызван, когда на объекте Active Record вызван touch.

class User < ApplicationRecord
  after_touch do |user|
    puts "You have touched an object"
  end
end

irb> u = User.create(name: 'Kuldeep')
=> #<User id: 1, name: "Kuldeep", created_at: "2013-11-25 12:17:49", updated_at: "2013-11-25 12:17:49">

irb> u.touch
You have touched an object
=> true

Он может быть использован совместно с belongs_to:

class Book < ApplicationRecord
  belongs_to :library, touch: true
  after_touch do
    puts 'A Book was touched'
  end
end

class Library < ApplicationRecord
  has_many :books
  after_touch :log_when_books_or_library_touched

  private
    def log_when_books_or_library_touched
      puts 'Book/Library was touched'
    end
end

irb> @book = Book.last
=> #<Book id: 1, library_id: 1, created_at: "2013-11-25 17:04:22", updated_at: "2013-11-25 17:05:05">

irb> @book.touch # triggers @book.library.touch
A Book was touched
Book/Library was touched
=> true

4. Запуск колбэков

Следующие методы запускают колбэки:

• create
• create!
• destroy
• destroy!
• destroy_all
• destroy_by
• save
• save!
• save(validate: false)
• toggle!
• touch
• update_attribute
• update
• update!
• valid?

Дополнительно, колбэк after_find запускается следующими поисковыми методами:

• all
• first
• find
• find_by
• find_by_*
• find_by_*!
• find_by_sql
• last

Колбэк after_initialize запускается всякий раз, когда инициализируется новый объект класса.

5. Пропуск колбэков

Подобно валидациям, также возможно пропустить колбэки, используя следующие методы.

• decrement
• decrement!
• decrement_counter
• delete
• delete_all
• delete_by
• increment
• increment!
• increment_counter
• insert
• insert!
• insert_all
• insert_all!
• touch_all
• update_column
• update_columns
• update_all
• update_counters
• upsert
• upsert_all

Однако, эти методы нужно использовать осторожно, поскольку важные бизнес-правила и логика приложения могут содержаться в колбэках. Пропуск их без понимания возможных последствий может привести к невалидным данным.

6. Прерывание выполнения

Как только вы зарегистрировали новые колбэки в своих моделях, они будут поставлены в очередь на выполнение. Эта очередь включает все валидации вашей модели, зарегистрированные колбэки и операции с базой данных для выполнения.

Вся цепочка колбэков упаковывается в операцию. Если любой колбэк вызывает исключение, выполняемая цепочка прерывается и запускается ROLLBACK. Чтобы преднамеренно остановить цепочку, используйте:

throw :abort

7. Колбэки для отношений

Колбэки работают с отношениями между моделями, и даже могут быть определены ими. Представим пример, где пользователь имеет много статей. Статьи пользователя должны быть уничтожены, если уничтожается пользователь. Давайте добавим колбэк after_destroy в модель User через ее отношения с моделью Article.

class User < ApplicationRecord
  has_many :articles, dependent: :destroy
end

class Article < ActiveRecord::Base
  after_destroy :log_destroy_action

  def log_destroy_action
    puts 'Article destroyed'
  end
end

irb> user = User.first
=> #<User id: 1>
irb> user.articles.create!
=> #<Article id: 1, user_id: 1>
irb> user.destroy
Article destroyed
=> #<User id: 1>

8. Условные колбэки

Как и в валидациях, возможно сделать вызов метода колбэка условным в зависимости от заданного предиката. Это осуществляется при использовании опций :if и :unless, которые могут принимать символ, Proc или массив.

Опцию :if следует использовать для определения, при каких условиях колбэк должен быть вызван. Если вы хотите определить условия, при которых колбэк не должен быть вызван, используйте опцию :unless.

8.1. Использование :if и :unless с Symbol

Опции :if и :unless можно связать с символом, соответствующим имени метода предиката, который будет вызван непосредственно перед вызовом колбэка.

При использовании опции :if, колбэк не будет выполнен, если метод предиката возвратит false; при использовании опции :unless, колбэк не будет выполнен, если метод предиката возвратит true. Это самый распространенный вариант.

class Order < ApplicationRecord
  before_save :normalize_card_number, if: :paid_with_card?
end

При использовании такой формы регистрации, также возможно зарегистрировать несколько различных предикатов, которые будут вызваны, чтобы проверить, должен ли выполняться колбэк. Мы раскроем это ниже.

8.2. Использование :if и :unless с Proc

Можно связать :if и :unless с объектом Proc. Этот вариант больше всего подходит при написании коротких методов, обычно однострочных.

class Order < ApplicationRecord
  before_save :normalize_card_number,
    if: Proc.new { |order| order.paid_with_card? }
end

Так как proc вычисляется в контексте объекта, также возможно написать так:

class Order < ApplicationRecord
  before_save :normalize_card_number, if: Proc.new { paid_with_card? }
end

8.3. Составные условия колбэков

Опции :if и :unless также принимают массив из proc или имен методов в виде символов:

class Comment < ApplicationRecord
  before_save :filter_content,
    if: [:subject_to_parental_control?, :untrusted_author?]
end

В список условий также можно запросто включить proc:

class Comment < ApplicationRecord
  before_save :filter_content,
    if: [:subject_to_parental_control?, Proc.new { untrusted_author? }]
end

8.4. Одновременное использование :if и :unless

В колбэках можно смешивать :if и :unless в одном выражении:

class Comment < ApplicationRecord
  before_save :filter_content,
    if: Proc.new { forum.parental_control? },
    unless: Proc.new { author.trusted? }
end

Колбэк запустится только когда все условия :if и не один из условий :unless будут истинны.

9. Классы колбэков

Иногда написанные вами методы колбэков достаточно полезны для повторного использования в других моделях. Active Record делает возможным создавать классы, включающие методы колбэка, так, что их можно использовать повторно.

Вот пример, где создается класс с колбэком after_destroy, чтобы разобраться с очисткой отвергнутых файлов в файловой системе. Это поведение может быть неуникальным для нашей модели PictureFile, и мы хотим поделиться им, таким образом хорошей идеей будет инкапсуляция его в отдельный класс. Это сделает более простым тестирование и изменение этого поведения.

class FileDestroyerCallback
  def after_destroy(file)
    if File.exist?(file.filepath)
      File.delete(file.filepath)
    end
  end
end

При объявлении внутри класса, как выше, методы колбэка получают объект модели как параметр. Это будет работать с любой моделью, которая использует класс подобным образом:

class PictureFile < ApplicationRecord
  after_destroy FileDestroyerCallback.new
end

Заметьте, что нам нужно создать экземпляр нового объекта FileDestroyerCallback, после того, как объявили наш колбэк как отдельный метод. Это особенно полезно, если колбэки используют состояние экземпляра объекта. Часто, однако, более подходящим является объявление его в качестве метода класса.

class FileDestroyerCallback
  def self.after_destroy(file)
    if File.exist?(file.filepath)
      File.delete(file.filepath)
    end
  end
end

Когда метод колбэка объявляется таким образом, нет необходимости создавать экземпляр объекта FileDestroyerCallback в нашей модели.

class PictureFile < ApplicationRecord
  after_destroy FileDestroyerCallback
end

Внутри своего колбэк-класса можно создать сколько угодно колбэков.

10. Транзакционные колбэки

10.1. Разбираемся с согласованностью

Имеются два дополнительных колбэка, которые включаются по завершению транзакции базы данных: after_commit и after_rollback. Эти колбэки очень похожи на колбэк after_save, за исключением того, что они не выполняются пока изменения в базе данных не будут подтверждены или обращены. Они наиболее полезны, когда вашим моделям Active Record необходимо взаимодействовать с внешними системами, не являющимися частью транзакции базы данных.

Рассмотрим, допустим, предыдущий пример, где модели PictureFile необходимо удалить файл после того, как запись уничтожена. Если что-либо вызовет исключение после того, как был вызван колбэк after_destroy, и транзакция откатывается, файл будет удален и модель останется в противоречивом состоянии. Например, предположим, что picture_file_2 в следующем коде не валидна, и метод save! вызовет ошибку.

PictureFile.transaction do
  picture_file_1.destroy
  picture_file_2.save!
end

Используя колбэк after_commit, можно учесть этот случай.

class PictureFile < ApplicationRecord
  after_commit :delete_picture_file_from_disk, on: :destroy

  def delete_picture_file_from_disk
    if File.exist?(filepath)
      File.delete(filepath)
    end
  end
end

10.2. Контекст имеет значение

Так как принято использовать колбэк after_commit только при создании, обновлении или удалении, есть псевдонимы для этих операций:

• after_create_commit
• after_update_commit
• after_destroy_commit

class PictureFile < ApplicationRecord
  after_destroy_commit :delete_picture_file_from_disk

  def delete_picture_file_from_disk
    if File.exist?(filepath)
      File.delete(filepath)
    end
  end
end

class User < ApplicationRecord
  after_create_commit :log_user_saved_to_db
  after_update_commit :log_user_saved_to_db

  private
    def log_user_saved_to_db
      puts 'User was saved to database'
    end
end

irb> @user = User.create # ничего не выводит

irb> @user.save # обновление @user
User was saved to database

10.3. after_save_commit

Также имеется after_save_commit, являющийся псевдонимом для использования колбэком after_commit вместе для создания и обновления:

class User < ApplicationRecord
  after_save_commit :log_user_saved_to_db

  private
    def log_user_saved_to_db
      puts 'User was saved to database'
    end
end

irb> @user = User.create # создание a User
User was saved to database

irb> @user.save # обновление @user
User was saved to database

10.4. Упорядочивание транзакционных колбэков

При определении нескольких транзакционных колбэков after_ (after_commit, after_rollback и т.д.), порядок будет обратным к тому, как они определены.

class User < ActiveRecord::Base
  after_commit { puts("это будет фактически вызвано вторым") }
  after_commit { puts("это будет фактически вызвано первым") }
end