Zeitwerk + Rails 6.1：控制器模块无法自动加载问题排查

问题场景 #

维护一个遗留Rails应用，将PostsController的CRUD操作拆分为多个模块，目录结构如下：

app/
  controllers/
    posts_controller/
      destroy.rb
      edit_and_update.rb
      index.rb
      new_and_create.rb
      show.rb
    posts_controller.rb

PostsController类中引入模块：

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  include Index
  include Show
  include NewAndCreate
  include EditAndUpdate
  include Destroy
end

模块定义示例：

# app/controllers/posts_controller/index.rb
module PostsController::Index
end

遇到的问题：

• 执行rails zeitwerk:check显示All is good!，但在测试中通过binding.break执行Post.const_get("PostsController")时，提示uninitialized constant PostsController::Index
• 若将app/controllers/posts_controller子目录添加到config.eager_load_paths，则报错expected file .../app/controllers/posts_controller/index.rb to define constant Index, but didn't

问题根源 #

1. Zeitwerk命名约定不匹配
   Zeitwerk期望文件路径直接对应常量名：app/controllers/posts_controller/index.rb应该定义顶级常量Index，但你定义的是嵌套常量PostsController::Index，这和Zeitwerk的自动加载规则冲突。虽然zeitwerk:check未报错，但实际加载时无法找到正确的常量。

2. include时的常量查找范围错误
   在PostsController类中include Index，Ruby会优先在PostsController的命名空间下查找Index常量（即PostsController::Index），但Zeitwerk根据路径只会加载顶级Index，导致找不到对应的嵌套常量。

解决方案 #

方案一：调整模块定义为顶级常量 #

修改每个模块文件的定义，让模块成为顶级常量，匹配Zeitwerk的路径规则：

# app/controllers/posts_controller/index.rb
module Index
end

这样Zeitwerk能正确加载顶级Index模块，PostsController中include Index也能找到对应的常量。

方案二：保持嵌套模块，调整定义与include写法 #

如果要保留PostsController::Index这种嵌套结构，需调整模块定义和include方式：

1. 修改模块文件，先打开PostsController命名空间再定义嵌套模块：

# app/controllers/posts_controller/index.rb
class PostsController
  module Index
  end
end

2. 在PostsController中include时使用完整嵌套路径：

class PostsController < ApplicationController
  include PostsController::Index
  include PostsController::Show
  # ... 其他模块
end

这种方式下不要把app/controllers/posts_controller添加到eager_load_paths，因为它已经是PostsController的嵌套常量目录，Zeitwerk会自动识别。

关键注意点 #

不要随意修改config.eager_load_paths，原目录结构下app/controllers已在加载路径中，子目录posts_controller会被Zeitwerk当作PostsController的嵌套常量目录处理，手动添加会破坏原有规则。

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