Rails Zeitwerk无法识别模块中的类，求排查原因

问题背景 #

执行rails zeitwerk:check命令时触发错误：

expected file app/api/mariana_tek_client.rb to define constant MarianaTekClient

但project/app/api/mariana_tek_client.rb中已按预期定义了带命名空间的类：

module Api
  class MarianaTekClient
    include HTTParty
  end
end

仅保留类定义（移除Api模块）时，Zeitwerk不再报错，但这样无法满足命名空间需求，且与文档描述冲突。

问题原因 #

Zeitwerk的核心规则是文件路径与常量名严格映射，但Rails默认未将app/api目录配置为Api命名空间的根目录：

• 当文件位于app/api/mariana_tek_client.rb时，Zeitwerk默认期望它定义顶级常量MarianaTekClient，而非Api::MarianaTekClient。
• 若要定义Api::MarianaTekClient，Zeitwerk默认会寻找路径app/api/api/mariana_tek_client.rb，这显然不符合常规开发习惯。

解决方案 #

在config/application.rb中手动配置Zeitwerk loader，将app/api目录与Api命名空间关联：

# config/application.rb
module YourAppName
  class Application < Rails::Application
    # ... 其他配置 ...
    
    # 配置app/api目录对应Api命名空间
    Rails.autoloaders.main.push_dir(Rails.root.join('app/api'), namespace: Api)
  end
end

配置完成后，重新执行rails zeitwerk:check即可通过校验，同时Api::MarianaTekClient能被正确加载。

内容的提问来源于stack exchange，提问作者Marin Zaimov