関連サイト: 関連URL

Active Record コールバック

このガイドでは、Active Recordオブジェクトのライフサイクルにフックをかける方法について説明します。

このガイドの内容:

1 オブジェクトのライフサイクル

Railsアプリケーションを普通に操作すると、その内部でオブジェクトが作成されたり、更新されたりdestroyされたりします。Active Recordはこのオブジェクトライフサイクルへのフックを提供しており、これを使用してアプリケーションやデータを制御できます。

コールバックは、オブジェクトの状態が切り替わる「前」または「後」にロジックをトリガします。

2 コールバックの概要

コールバックとは、オブジェクトのライフサイクル期間における特定の瞬間に呼び出されるメソッドのことです。コールバックを利用することで、Active Recordオブジェクトが作成/保存/更新/削除/検証/データベースからの読み込み、などのイベント発生時に常に実行されるコードを書くことができます。

2.1 コールバックの登録

コールバックを利用するためには、コールバックを登録する必要があります。コールバックの実装は普通のメソッドと特に違うところはありません。これをコールバックとして登録するには、マクロのようなスタイルのクラスメソッドを使用します。

class User < ActiveRecord::Base
  validates :login, :email, presence: true

  before_validation :ensure_login_has_a_value

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

このマクロスタイルのクラスメソッドはブロックを受け取ることもできます。以下のようにコールバックしたいコードがきわめて短く、1行に収まるような場合にこのスタイルを使ってみます。

class User < ActiveRecord::Base
  validates :login, :email, presence: true

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

コールバックは、特定のライフサイクルのイベントでのみ呼び出されるように登録することもできます。

class User < ActiveRecord::Base
  before_validation :normalize_name, on: :create

  # :onは配列を取ることもできる
  after_validation :set_location, on: [ :create, :update ]

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

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

コールバックの宣言はprotectedまたはprivateキーワードの後で行なうのが好ましい方法です。コールバックメソッドがpublicな状態のままだと、このメソッドがモデルの外から呼び出され、オブジェクトのカプセル化の原則に違反する可能性があります。

3 利用可能なコールバック

Active Recordで利用可能なコールバックの一覧を以下に示します。これらのコールバックは、実際の操作中に呼び出される順序に並んでいます。

3.1 オブジェクトの作成

  • before_validation
  • after_validation
  • before_save
  • around_save
  • before_create
  • around_create
  • after_create
  • after_save

3.2 オブジェクトの更新

  • before_validation
  • after_validation
  • before_save
  • around_save
  • before_update
  • around_update
  • after_update
  • after_save

3.3 オブジェクトのdestroy

  • before_destroy
  • around_destroy
  • after_destroy

after_saveは作成と更新の両方で呼び出されますが、コールバックマクロの呼び出し順にかかわらず、必ず、より具体的なafter_createおよびafter_updateより に呼び出されます。

3.4 after_initializeafter_find

after_initializeコールバックは、Active Recordオブジェクトが1つインスタンス化されるたびに呼び出されます。インスタンス化は、直接newを実行する他にデータベースからレコードが読み込まれるときにも行われます。これを利用すれば、Active Recordのinitializeメソッドを直接オーバーライドせずに済みます。

after_findコールバックは、Active Recordがデータベースからレコードを1つ読み込むたびに呼び出されます。after_findafter_initializeが両方定義されている場合は、after_findが先に実行されます。

after_initializeafter_findコールバックには、対応するbefore_*メソッドはありませんが、他のActive Recordコールバックと同様に登録できます。

class User < ActiveRecord::Base
  after_initialize do |user|
    puts "オブジェクトは初期化されました"
  end

  after_find do |user|
    puts "オブジェクトが見つかりました"
  end
end

>> User.new
オブジェクトは初期化されました
=> #<User id: nil>

>> User.first
オブジェクトが見つかりました
オブジェクトは初期化されました
=> #<User id: 1>

3.5 after_touch

after_touchコールバックは、Active Recordオブジェクトがタッチされるたびに呼び出されます。

class User < ActiveRecord::Base
  after_touch do |user|
    puts "オブジェクトにタッチしました"
  end
end

>> 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">

>> u.touch
オブジェクトにタッチしました
=> true

このコールバックはbelongs_toと併用できます。

class Employee < ActiveRecord::Base
  belongs_to :company, touch: true
  after_touch do
    puts 'Employeeモデルにタッチされました'
  end
end

class Company < ActiveRecord::Base
  has_many :employees
  after_touch :log_when_employees_or_company_touched

  private
  def log_when_employees_or_company_touched
    puts 'Employee/Companyにタッチされました'
  end
end

>> @employee = Employee.last
=> #<Employee id: 1, company_id: 1, created_at: "2013-11-25 17:04:22", updated_at: "2013-11-25 17:05:05">

# @employee.company.touchをトリガーする
>> @employee.touch
Employee/Companyにタッチされました
Employeeにタッチされました
=> true

4 コールバックの実行

以下のメソッドはコールバックをトリガします。

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

また、after_findコールバックは以下のfinderメソッドを実行すると呼び出されます。

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

after_initializeコールバックは、そのクラスの新しいオブジェクトが初期化されるたびに呼び出されます。

find_by_*メソッドとfind_by_*!メソッドは、属性ごとに自動的に生成される動的なfinderメソッドです。詳細については動的finderのセクションを参照してください。

5 コールバックをスキップする

検証(validation)の場合と同様、以下のメソッドを使用するとコールバックをスキップできます。

  • decrement
  • decrement_counter
  • delete
  • delete_all
  • increment
  • increment_counter
  • toggle
  • touch
  • update_column
  • update_columns
  • update_all
  • update_counters

重要なビジネスルールやアプリケーションロジックはたいていコールバックに仕込まれていますので、これらのメソッドの使用には十分気をつけてください。コールバックをうかつにバイパスすると、データの不整合が発生する可能性があります。

6 コールバックの停止

モデルに新しくコールバックを登録すると、コールバックは実行キューに入ります。このキューには、あらゆるモデルに対する検証、登録済みコールバック、実行待ちのデータベース操作が置かれます。

コールバックの連鎖の全体は、1つのトランザクションに含まれます。before コールバックの1つがfalseを返すか例外を発生するという動作をする場合、実行の連鎖全体が停止してロールバックが発行されます。after コールバックの場合は例外を発生することによってのみ、コールバック連鎖の停止とトランザクションのロールバックを実行させることができます。

ActiveRecord::Rollback以外の例外は、その例外によってコールバック連鎖が停止した後で、Railsによって再び発生させられます。このため、ActiveRecord::Rollback以外の例外を発生させると、saveやupdate_attributesのようなメソッド (つまり通常trueをfalseを返そうとするメソッド) が、例外を起こすことを想定していないコードを破壊する恐れがあります。

7 リレーションシップのコールバック

コールバックはモデルのリレーションシップを経由して動作できます。また、リレーションシップを使用してコールバックを定義することすらできます。1人のユーザーが多数のポストを持っている状況を例に取ります。あるユーザーが所有するポストは、そのユーザーがdestroyされたらdestroyされる必要があります。Userモデルにafter_destroyコールバックを追加し、このコールバックでPostモデルへのリレーションシップを経由すると以下のようになります。

class User < ActiveRecord::Base
  has_many :posts, dependent: :destroy
end

class Post < ActiveRecord::Base
  after_destroy :log_destroy_action

  def log_destroy_action
    puts 'Post destroyed'
  end
end

>> user = User.first
=> #<User id: 1>
>> user.posts.create!
=> #<Post id: 1, user_id: 1>
>> user.destroy
Post destroyed
=> #<User id: 1>

8 条件付きコールバック

検証と同様、与えられた述語による条件を満たす場合に実行されるコールバックメソッドの呼び出しを作成することもできます。これを行なうには、コールバックで:ifオプションまたは:unlessオプションを使用します。このオプションはシンボル、文字列、Proc、またはArrayを引数に取ります。特定の状況でのみコールバックが呼び出される必要がある場合は、:ifオプションを使用します。特定の状況ではコールバックを呼び出してはならない場合は、:unlessオプションを使用します。

8.1 :ifおよび:unlessオプションでシンボルを使用する

:ifオプションまたは:unlessオプションは、コールバックの直前に呼び出される述語メソッド(訳注: trueかfalseのいずれかの値のみを返すメソッド)の名前に対応するシンボルと関連付けることができます。:ifオプションを使用する場合、述語メソッドがfalseを返せばコールバックは実行されません。:unlessオプションを使用する場合、述語メソッドがtrueを返せばコールバックは実行されません。これはコールバックで最もよく使用されるオプションです。この方法で登録することで、いくつもの異なる述語メソッドを登録して、コールバックを呼び出すべきかどうかをチェックすることができます。

class Order < ActiveRecord::Base
  before_save :normalize_card_number, if: :paid_with_card?
end

8.2 :ifおよび:unlessオプションで文字列を使用する

文字列を使用することもできます。この文字列は後でevalで評価されるため、実行可能な正しいRubyコードを含んでいる必要があります。オプションで文字列を使用するのは、文字列に含まれる条件が十分に短い場合だけにしてください。

class Order < ActiveRecord::Base
  before_save :normalize_card_number, if: "paid_with_card?"
end

8.3 :ifおよび:unlessオプションでProcを使用する

最後に、:ifおよび:unlessオプションでProcオブジェクトを使用することもできます。このオプションは、1行以内に収まるワンライナーで検証を行う場合に最適です。

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

8.4 コールバックで複数の条件を指定する

1つの条件付きコールバック宣言内で、:ifオプションと:unlessオプションを同時に使用することができます。

class Comment < ActiveRecord::Base
  after_create :send_email_to_author, if: :author_wants_emails?,
    unless: Proc.new { |comment| comment.post.ignore_comments? }
end

9 コールバッククラス

うまく書けたコールバックメソッドを他のモデルでも使い回したくなることもあります。Active Recordは、コールバックメソッドをカプセル化したクラスを作成できますので、簡単に再利用できます。

以下の例では、PictureFileモデル用にafter_destroyコールバックを持つクラスを作成しています。

class PictureFileCallbacks
  def after_destroy(picture_file)
    if File.exist?(picture_file.filepath)
      File.delete(picture_file.filepath)
    end
  end
end

上のようにクラス内で宣言することにより、コールバックメソッドはモデルオブジェクトをパラメータとして受け取れるようになります。これでこのコールバッククラスをモデルで使用できます。

class PictureFile < ActiveRecord::Base
  after_destroy PictureFileCallbacks.new
end

コールバックをインスタンスメソッドとして宣言したので、PictureFileCallbacksオブジェクトを新しくインスタンス化する必要があったことにご注意ください。これは、インスタンス化されたオブジェクトの状態をコールバックメソッドで利用したい場合に特に便利です。ただし、コールバックをクラスメソッドとして宣言する方がわかりやすいこともしばしばあります。

class PictureFileCallbacks
  def self.after_destroy(picture_file)
    if File.exist?(picture_file.filepath)
      File.delete(picture_file.filepath)
    end
  end
end

コールバックメソッドを上のように宣言した場合は、PictureFileCallbacksオブジェクトのインスタンス化は不要です。

class PictureFile < ActiveRecord::Base
  after_destroy PictureFileCallbacks
end

コールバッククラスの内部では、いくつでもコールバックを宣言できます。

10 トランザクションコールバック

データベースのトランザクションが完了したときにトリガされるコールバックが2つあります。after_commitafter_rollbackです。これらのコールバックはafter_saveコールバックときわめて似通っていますが、データベースの変更のコミットまたはロールバックが完了するまでトリガされない点が異なります。これらのメソッドは、Active Recordのモデルから、データベーストランザクションの一部に含まれていない外部のシステムとやりとりを行ないたい場合に特に便利です。

例として、直前の例に使用したPictureFileモデルで、対応するレコードがdestroyされた後にファイルを1つ削除する必要があるとしましょう。after_destroyコールバックの直後に何らかの例外が発生してトランザクションがロールバックすると、ファイルが削除され、モデルの一貫性が損なわれたままになります。ここで、以下のコードにあるpicture_file_2オブジェクトが無効で、save!メソッドがエラーを発生するとします。

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

after_commitコールバックを使用することで、このような場合に対応することができます。

class PictureFile < ActiveRecord::Base
  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

:onオプションは、コールバックがトリガされる条件を指定します。:onオプションを指定しないと、あらゆるアクションでコールバックがトリガされまくります。

after_commitコールバックおよびafter_rollbackコールバックは、1つのトランザクションブロック内におけるあらゆるモデルの作成/更新/destroy時に呼び出されます。これらのコールバックのいずれかで何らかの例外が発生すると、例外は無視されるため、他のコールバックに干渉しません。従って、もし自作のコールバックが例外を発生する可能性がある場合は、自分のコールバック内でrescueし、適切にエラー処理を行なう必要があります。

フィードバックについて

本ガイドは GitHub上の yasslab/railsguides.jp で管理・公開されております。 本ガイドを読んで気になる文章や間違ったコードを見かけたら、上記リポジトリにてお気軽に Issue を出して頂けると嬉しいです。また、「Pull Request を送りたい!」という場合には、Ruby on Railsガイドのガイドラインと、READMEに記載されている「翻訳の流れ」をご参考にしてください。

なお、原著における間違いを見つけたら、「Ruby on Railsに貢献する方法」に記されているRailsのドキュメントに貢献するを参考にしながら、ぜひRailsコミュニティに貢献してみてしてください :)

本ガイドの品質向上に向けて、皆さまのご協力が得られれば幸いです。よろしくお願い致します。

  1. このエントリーをはてなブックマークに追加