Since Ruby 2.5 top-level constant lookup ("the bad") has been removed.
Since Rails 6 autoloading ("the ugly") is done using Zeitwerk, which fixes most edge cases.
In Ruby, classes and modules are called constants. This card explains how Ruby resolves the meaning of a constant.
E. g. in the following example,
Array could mean either
Foo::Array or simply
class Foo def list Array.new end end
What Ruby does here is to see if the name
Array makes sense inside of
Foo::, and if that fails, resolves it to
::Array (without a namespace).
This is relevant for old Ruby versions. Ruby 2.5+ removes top-level constant lookup which means that
Array::String will not resolve to
String and raise an error instead.
You might be surprised that these are all valid ways to reference Ruby's
String Array::String Array::Hash::String
When you see
Array::String, do not think "a class
String inside the
Array namespace". Rather think: "What does
String resolve to from the viewpoint of the
When you do this, Ruby will print a warning:
warning: toplevel constant String referenced by Array::String
However, that warning is usually lost in a sea of log messages. And here is where it gets ugly (see below).
This part is a bit lengthy, but it allows you to debug strange bugs with Rails autoloading the wrong constants. Due to the constant lookup rules above, Rails sometimes guesses wrong and loads the wrong file. This happens when you heavily namespace your models. The mechanism how files are loaded differs in development and production, but the problem exist for both environment.
During development, Rails unloads all classes after every request. This way code changes take effect immediately, without requiring you to restart the server. If you have been working with Rails for a while, you might even have forgotten that this is a feature of Rails. In the regular world of Ruby, classes don't refresh themselves automatically after a change.
Rails also autoloads classes on demand during development. This means every request begins with none of your models, controllers, loaded. Whenever Ruby encounters a constant name it doesn't know yet, it guesses the correct
.rb file and
requires the file. Again, this is a feature activated by Rails. If you write a regular Ruby script without Rails, you need to
require all the files you want to use. Classes don't magically load themselves from disk.
All files are loaded in a deterministic order once the server boots.
Take this example with some constants referencing each other:
# app/models/contract/document/uploader.rb class Contract::Document::Uploader < CarrierWave::Uploader::Base ... end # app/models/document/uploader.rb class Document::Uploader < CarrierWave::Uploader::Base ... end # app/models/document.rb class Document < ActiveRecord::Base mount_uploader Document::Uploader end # app/models/contract.rb class Contract < ActiveRecord::Base mount_uploader Contract::Document::Uploader end
In the example above it can happen that the
Contract class actually mounts the uploader
Document::Uploader instead of the requested
In development this can happen randomly, as you never know in which order the files are autoloaded. If the autoload mechanism has already loaded
app/models/document/uploader.rb, a constant lookup for
Contract::Document::Uploader will never fail as it is actually a valid way to reference
Document::Uploader. The file
app/models/contract/document/uploader.rb is never autoloaded.
In production you either have the issue or not. The order
app/models/document/uploader.rb > app/models/contract.rb > ... will have unexpected references, whereas the order
app/models/contract/document/uploader.rb > app/models/document/uploader.rb > app/models/contract.rb > ... will reference the classes as expected.
Api::Userwhen you also have a
require_dependencyif the fix above is not possible