Classic から Zeitwerk への移行

本ガイドでは、Railsアプリケーションをclassicモードからzeitwerkモードに移行する方法について解説します。

このガイドの内容

  • classicモードとzeitwerkモードについて
  • classicからzeitwerkに切り替える理由
  • zeitwerkモードを有効にする
  • アプリケーションがzeitwerkモードで動いていることを検証する
  • プロジェクトが正しく読み込まれることをコマンドラインで検証する
  • プロジェクトが正しく読み込まれることをテストスイートで検証する
  • 想定されるエッジケースの対応方法
  • Zeitwerkで利用できる新機能

📜 お知らせ: Railsガイドが Carbon Ads for Open Source の対象になりました

1 classicモードとzeitwerkモードについて

Railsは最初期からRails 5まで、Active Supportで実装されたオートローダーを用いていました。このオートローダーはclassicと呼ばれ、Rails 6.xでは引き続き利用可能です。Rails 7ではclassicオートローダーが含まれなくなりました。

Rails 6から、より優れた新しいオートロード方法がRailsに搭載されました。これはZeitwerkというgemに一任されています。これがzeitwerkモードです。デフォルトでは、Railsフレームワーク6.0および6.1の読み込みはデフォルトでzeitwerkモードで実行され、Rails 7で利用できるのはzeitwerkモードのみとなります。

2 classicからzeitwerkに切り替える理由

classicオートローダーは非常に便利でしたが、取り扱いに少々注意を要したり時に混乱を招いたりする問題が多数存在していました。Zeitwerkはこうした問題を解決するために開発されました(その他にもさまざまな動機があります)。

classicモードは非推奨化されたので、Railsを6.xにアップグレードする際にzeitwerkモードに移行することを強く推奨します。

この移行はRails 7で完了し、classicモードが含まれなくなりました。

3 「移行するのが怖いんですが」

大丈夫です。

Zeitwerkは従来のオートローダーとの互換性をできるだけ維持するように設計されています。現在のアプリケーションでオートロードが正しく行われていれば、切り替えは簡単です。大小さまざまなプロジェクトで、スムーズに切り替えられたことが報告されています。

本ガイドを読めば、安心してオートローダーを切り替えられます。

何らかの理由で解決方法が見当たらない状況に直面した場合は、 お気軽にrails/railsリポジトリのissueをオープンして、@fxnにメンションしてください。

4 zeitwerkモードを有効にする

4.1 Rails 5.x以前のアプリケーションの場合

Rails 6.0より前のバージョンを実行するアプリケーションではzeitwerkモードを利用できません。最低でもRails 6.0にする必要があります。

4.2 Rails 6.xアプリケーションの場合

Rails 6.xアプリケーションの場合は以下の2とおりのシナリオがあります。

アプリケーションがRails 6.0または6.1のフレームワークのデフォルトを読み込んでいて、かつclassicモードで実行されている場合は、classicモードを手動でオプトアウトしなければなりません。これは以下のような形で行う必要があります。

# config/application.rb
config.load_defaults 6.0
config.autoloader = :classic # この行を削除する

上のコメントにあるように、このオーバーライドを削除するとzeitwerkモードがデフォルトになります。

一方、アプリケーションが古いフレームワークのデフォルトを読み込んでいる場合は、以下のようにzeitwerkモードを明示的に有効にする必要があります。

# config/application.rb
config.load_defaults 5.2
config.autoloader = :zeitwerk

4.3 Rails 7アプリケーションの場合

Rails 7にはzeitwerkモードしかないので、このモードを有効するために設定を変更する必要はありません。

Rails 7ではconfig.autoloader=設定そのものがなくなりました。config/application.rbにこの設定がある場合は、その行を削除してください。

5 アプリケーションがzeitwerkモードで動いていることを検証する

アプリケーションがzeitwerkモードで動いていることを検証するには、以下を実行します。

bin/rails runner 'p Rails.autoloaders.zeitwerk_enabled?'

trueが出力されれば、zeitwekモードが有効です。

6 アプリケーションがZeitwerkに沿っているかを確かめる

zeitwerkモードを有効にしてから、以下を実行します。

bin/rails zeitwerk:check

チェックが成功すると以下のように出力されます。

% bin/rails zeitwerk:check
Hold on, I am eager loading the application.
All is good!

アプリケーションの設定によってはこの他にも出力されることがありますが、末尾に"All is good!"があればOKです。

Zeitwerkで期待される定数が定義されていないファイルがあると、上のタスクで通知されます。このタスクは1ファイルごとに実行されます。問題が生じたときにタスクが先に進むと、あるファイルの読み込み失敗が他の無関係な失敗に連鎖してエラー出力が読みにくくなるためです。

定数にひとつでも問題があれば、その問題を解決し、"All is good!"が出力されるまでタスクを再実行します。

たとえば以下のように出力されたとします。

% bin/rails zeitwerk:check
Hold on, I am eager loading the application.
expected file app/models/vat.rb to define constant Vat

VATはヨーロッパの税制のことです。 app/models/vat.rbではVATが定義済みですが、オートローダーはVatを期待しています。どんな理由でこうなったのでしょうか。

6.1 略語の扱い

これはZeitwerkで最もありがちな問題で、略語が関係しています。このエラーメッセージが生じた理由を考えてみましょう。

classicオートローダーは、すべて大文字のVATをオートロードできます。その理由は、オートローダーの入力にconst_missingの定数名が使われるからです。VATという定数に対してunderscoreが呼び出されてvatが生成され、これを元にvat.rbというファイルを検索し、ファイルは正常に見つかります。

新しいZeitwerkオートローダーの入力はファイルシステムになっています。vat.rbというファイルがあると、Zeitwerkはvatに対してcamelizeを呼び出し、冒頭のみが大文字のVatが生成されます。これにより、Vatという定数名が定義されていることが期待されます。以上がエラーメッセージの内容です。

これは、以下のようにActiveSupport::Inflectorの語尾活用機能を用いて略語を指定するだけで簡単に修正できます。

# config/initializers/inflections.rb
ActiveSupport::Inflector.inflections(:en) do |inflect|
  inflect.acronym "VAT"
end

上の方法は、Active Supportの語尾活用機能をグローバルに変更します。これで問題ない場合もありますが、オートローダーで用いられる語尾活用機能にオーバーライドを渡したい場合は、以下のようにします。

# config/initializers/zeitwerk.rb
Rails.autoloaders.each do |autoloader|
  autoloader.inflector.inflect("vat" => "VAT")
end

以上を反映すればチェックはパスします。

% bin/rails zeitwerk:check
Hold on, I am eager loading the application.
All is good!

6.2 concernsについて

以下のように、concernsサブディレクトリを持つ標準的な構造からのオートロードやeager loadingを行えます【チェック】。

app/models
app/models/concerns

app/models/concernsディレクトリはデフォルトではオートロードのパスに属しているので、これがルートディレクトリと見なされます。そのため、デフォルトではapp/models/concerns/foo.rbファイルで定義されるのはConcerns::FooではなくFooになります。

アプリケーションでConcernsが名前空間として使われている場合は、以下の2つの方法があります。

  1. これらのクラスやモジュールからConcerns名前空間を削除してクライアントコードを更新する。
  2. オートロードのパスからapp/models/concernsを除外することで現状のままにする。
  # config/initializers/zeitwerk.rb
  ActiveSupport::Dependencies.
    autoload_paths.
    delete("#{Rails.root}/app/models/concerns")

6.3 オートロードのパスにappを追加する

プロジェクトによっては、たとえばAPI::Baseを定義するapp/api/base.rbを置き、オートロードパスにappを追加することで利用したい場合もあります。

Railsは自動的にappのすべてのサブディレクトリもオートロードパスに追加するので(アセットのディレクトリなどは除く)、app/models/concernsで起きたのと似たようなネステッドrootディレクトリの問題がここでも起きます。今後この設定はこのままでは機能しません。

ただし、以下のようにイニシャライザでオートロードパスからapp/apiを削除すれば現状の構造を維持できます。

# config/initializers/zeitwerk.rb
ActiveSupport::Dependencies.
  autoload_paths.
  delete("#{Rails.root}/app/api")

6.4 オートロードした定数と明示的な名前空間

ファイル内で、たとえば以下のようにHotelという名前空間が定義されているとします。

app/models/hotel.rb         # Hotelを定義する
app/models/hotel/pricing.rb # Hotel::Pricingを定義する

このHotel定数は、以下のようにclassまたはmoduleキーワードで設定しなければなりません。

class Hotel
end

上は問題ありません。

ただし、以下は無効です。

Hotel = Class.new

または

Hotel = Struct.new

これらはHotel::Pricingなどの子オブジェクトを探索できません。

これらの制約は、明示的な名前空間にのみ適用されます。名前空間を定義しないクラスやモジュールであれば上述の記法でも定義できます。

6.5 1ファイルに1定数(同一トップレベルあたり)

classicモードでは、以下のように同一トップレベルに複数の定数を定義して、それらすべてを再読み込みすることも技術的に可能でした。以下のコード例で考えます。

# app/models/foo.rb

class Foo
end

class Bar
end

上のBarは本来オートロードできないにもかかわらず、FooをオートロードするとBarもオートロードされました。

これはzeitwerkモードでは利用できません。Barは専用のbar.rbファイルに移動する必要があります。1ファイルにつきトップレベル定数1個という規則です。

これが影響するのは、上のコード例のように同一トップレベルに置かれた定数だけです。以下のようなネストしたクラスやモジュールには影響しません。

# app/models/foo.rb

class Foo
  class InnerClass
  end
end

アプリケーションがFooを再読み込みすると、Foo::InnerClassも再読み込みされます。

6.6 config.autoload_pathsについて

以下のようにワイルドカードを含む設定では注意が必要です。

config.autoload_paths += Dir["#{config.root}/extras/**/"]

config.autoload_pathsのどの要素もトップレベルの名前空間(Object)を表さなければならないので、上の設定は無効です。

これは、以下のようにワイルドカードを削除するだけで修正できます。

config.autoload_paths << "#{config.root}/extras"

6.7 spring gemとtest環境

spring gemは、アプリケーションコードが変更されると再読み込みします。test環境でこの再読み込みを有効にするには、以下のようにする必要があります。

# config/environments/test.rb
config.cache_classes = false

そうしないと、以下のエラーが発生します。

reloading is disabled because config.cache_classes is true

この設定でパフォーマンスは落ちません。

6.8 bootsnap gem

少なくともbootsnap 1.4.4以上に依存するようにしてください。

7 Zeitwerk準拠をテストスイートでチェックする

Rakeタスクzeitwerk:checkは、単にeager loadingを実行します。これによってZeitwerkの組み込みバリデーションがトリガされます。

これと同等のタスクをテストスイートに追加すれば、テストカバレッジに関係なくアプリケーションの読み込みが常に正しく行われるようになります。

7.1 minitestの場合

require "test_helper"

class ZeitwerkComplianceTest < ActiveSupport::TestCase
  test "eager loads all files without errors" do
    Rails.application.eager_load!
  rescue => e
    flunk(e.message)
  else
    pass
  end
end

7.2 RSpecの場合

require "rails_helper"

RSpec.describe "Zeitwerk compliance" do
  it "eager loads all files without errors" do
    expect { Rails.application.eager_load! }.not_to raise_error
  end
end

8 Zeitwerkで利用できる新機能

8.1 require_dependency呼び出しの削除

Zeitwerkによって、require_dependencyの既知のユースケースはすべて削除されました。プロジェクトをgrepしてrequire_dependencyをすべて削除してください。

アプリケーションでSTIを利用している場合は、『定数の自動読み込みと再読み込み (Zeitwerk)ガイド』の『STI(単一テーブル継承)』を参照してください。

8.2 クラスやモジュールの定義内で定数名を修飾可能になった

クラスやモジュールの定義で、以下のような定数パスを安定して利用できるようになりました。

# このクラスの本体でのオートロードがRubyのセマンティクスと一致するようになった
class Admin::UsersController < ApplicationController
  # ...
end

ひとつ注意すべきは、実行順序によってはclassicオートローダーで以下のFoo::Wadusをオートロードできる場合があった点です。

class Foo::Bar
  Wadus
end

このFooはネストの中に存在しないので、上はRubyのセマンティクスと一致しません。そのため、これはzeitwerkモードではまったく動作しません。もしこうしたエッジケースに遭遇した場合は、以下のようにFoo::Wadusという修飾名を利用できます。

class Foo::Bar
  Foo::Wadus
end

あるいは、以下のようにFooをネストに追加します。

module Foo
  class Bar
    Wadus
  end
end

8.3 あらゆる場所でスレッドセーフになる

RailsにはWebリクエストをスレッドセーフにするロックが用意されているにもかかわらず、classicモードの定数自動読み込みはスレッドセーフではありません。

zeitwerkモードの定数自動読み込みはスレッドセーフです。たとえば、runnerコマンドで実行されるマルチスレッドのスクリプトをオートロードできるようになりました。

8.4 eager loadingとオートロードが一貫するようになった

classicモードでは、app/models/foo.rbファイルでBarが定義されていると、このファイルをオートロードできません。しかしclassicモードはファイルの読み込みを盲目的に再帰するので、このファイルのeager loadingは可能です。テストを最初にeager loadingする形で実行すると、その後に行われるオートロードで実行が失敗する可能性があります。

zeitwerkモードではどちらの読み込みモードも一貫しているので、テストの失敗やエラーは同じファイル内で発生します。

フィードバックについて

Railsガイドは GitHub の yasslab/railsguides.jp で管理・公開されております。本ガイドを読んで気になる文章や間違ったコードを見かけたら、上記リポジトリにてお気軽に Pull Request を出して頂けると嬉しいです。Pull Request の送り方については GitHub の README をご参照ください。

原著における間違いを見つけたら『Rails のドキュメントに貢献する』を参考にしながらぜひ Rails コミュニティに貢献してみてください 🛠💨✨

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

YassLab 株式会社
https://yasslab.jp/

支援・協賛

Railsガイドは下記のサポーターから継続的な支援を受けています。Railsガイドへの支援・協賛にご興味あれば info@yasslab.jp までお問い合わせください。

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