RailsのZeitwerk化でやったこと、見落としていたこと #Ruby

Railsアプリケーションで、classicオートローダーを使っているものがあったのですが、Rails v7からはZeitwerkしか使えなくなってしまうのでZeitwerkへ移行しました。

手順は基本的にはRailsガイドに乗っているのですが、やりながら詰まったところ等もあったので記事にまとめました。

やったこと

やったことは大きく、以下3点です。

autoloaderを:zeitwerkに変更して、bin/rails zeitwerk:checkでエラーが出た部分を修正
不要な自動読み込みを削除
アプリケーション起動時の自動読み込みの修正

1つ目は比較的すぐ完了しましたが、2と3については少し時間がかかった部分もありました。

1. autoloaderを`:zeitwerk`に変更して、`bin/rails zeitwerk:check`でエラーが出た部分を修正

bin/rails zeitwerk:checkでチェックができるのですが、このときエラーが出たのは主に略語の扱いでした。

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

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

全て大文字の略語が使われているクラスがいくつかあったので、都度判断して修正しました。

2. 不要な自動読み込みを削除

自動読み込みパスに入っていながら、本番環境で使っていないコードがありました。
全て精査する必要はないとは思いますが、今回「development以外の環境でのみ」エラーが発生していました。

原因としては、自動読み込みパスにあるファイルから、developmentでしかインストールしていないgemを require していたためです。

対応としては、

対象のファイルを Rails.autoloaders.main.ignore で自動読み込みパスから除外する
development等で実行しているファイルから require で個別読み込みする

の順で行いました。

ちなみに、このファイルはlib配下にあり、今まではlibを全て自動読み込みパスに入れていたのですが、この場合Rails v7.1からはconfig.autoload_libを使うことでシンプルな設定ができます。

このように、本番環境でのみエラーが発生する可能性があるので、RAILS_ENV=production等の環境でもzeitwerk:checkをしておくのをおすすめします

3. アプリケーション起動時の自動読み込みの修正

2までで、アプリケーションを起動してもエラーは発生しなくなりました。しかし、エラーは出ないものの、意図しない挙動が発生している可能性があります。

特に、アプリケーション起動時に実行するconfig/initializersの設定から、自動読み込みパスにあるファイルを読み込む時に注意が必要です。

具体的には、アプリケーション起動時に、以下の点への影響確認が必要です。

(1) 自動読み込みパスにあるファイルを自動読み込みすると deprecation warning が表示される
(2) 再読み込み可能なクラスへの設定等の処理は、起動後に設定がリセットされる
(3) 再読み込みが有効な場合、起動時に参照したクラスが更新されても、起動時におこなった設定は古いキャッシュを参照してしまう

(1) 自動読み込みパスにあるファイルを自動読み込みすると deprecation warning が表示される

log/development.log に以下のような DEPRECATION WARNING が表示されていました。

DEPRECATION WARNING: Initialization autoloaded the constants XxxYyyZzz.

Being able to do this is deprecated. Autoloading during initialization is going
to be an error condition in future versions of Rails.

Reloading does not reboot the application, and therefore code executed during
initialization does not run again. So, if you reload XxxYyyZzz, for example,
the expected changes won't be reflected in that stale Class object.

These autoloaded constants have been unloaded.

In order to autoload safely at boot time, please wrap your code in a reloader
callback this way:

    Rails.application.reloader.to_prepare do
      # Autoload classes and modules needed at boot time here.
    end

That block runs when the application boots, and every time there is a reload.
For historical reasons, it may run twice, so it has to be idempotent.

Check the "Autoloading and Reloading Constants" guide to learn more about how
Rails autoloads and reloads.

最初の3行に以下のようにあります。

DEPRECATION WARNING: Initialization autoloaded the constants XxxYyyZzz.

Being able to do this is deprecated. Autoloading during initialization is going
to be an error condition in future versions of Rails.

以下の記事でも説明されていますが、アプリケーション起動時 (config/initializers等) に自動読み込みをしようとしたとき、Zeitwerkはまだ起動しておらず、今後エラーが発生する可能性があります。

そのため、読み込みが必要なものを明示的に require で読み込む対応を行いました。

(2) 再読み込み可能なクラスへの設定等の処理は、起動後に設定がリセットされる

結論から言うと、この点について今回対応は不要でしたが、記載します。

Railsガイドでいうと、 9.1 ユースケース1: 起動中に、再読み込み可能なコードを読み込むに記載されています。

再読み込みは config.enable_reloading で設定されています。
再読み込みが有効な場合（主にdevelopment環境）、クラスが再読み込みされる際にクラスのunloadが行われるため、起動時に以下のような設定を設定していたとしても設定がリセットされてしまいます。
(Railsガイドからサンプルを引用)

ApiGateway.endpoint = "https://example.com"

再読み込み後にも適用したい場合は、Rails.application.config.to_prepareやRails.application.config.after_initializeを使う必要があるようです。

(3) 再読み込みが有効な場合、起動時に参照したクラスが更新されても、起動時におこなった設定は古いキャッシュを参照してしまう

例えば、以下のように、再読み込みされないオブジェクトに、再読み込み可能なクラスを使うことがあります。

# HogeMiddleware は再読み込み可能
Rails.application.config.middleware.use HogeMiddleware

この場合、HogeMiddlewareが再読み込みされたとしても、config.middlewareに設定されたものは再読み込みする前の古いキャッシュを参照するので、混乱の元となります。

このように、再読み込みされないオブジェクトへ設定するものは再読み込みの対象外とするのが良いです。
具体的には、

Rails.autoloaders.main.ignore等で対象のファイルを自動読み込みの対象外にした上で require する
config.autoload_once_pathsで再読み込みせずに自動読み込みをする

のような方法があります。

今回は自動読み込みする必要がなかったので、前者の方法で対応を行いました。

これで完了

以上を行うことで、問題なくリリースすることができました。
実は、Zeitwerk化は3年前にも一度試したものの、断念した形跡があったので、3年越しのリリースとなってしまいました。

個人的には、開発環境以外でのみ読み込みエラーが発生する件や、log/development.logにwarningが出ている件は見落としがちだと思ったので、他に対応される方がいればご注意ください。

RailsのZeitwerk化でやったこと、見落としていたこと