非Rails大型Ruby项目适配Zeitwerk的检测方案咨询

一、先搞定问题检测 #

1. 命名规范排查 #

• 手动抽核心文件检查：重点核对类/模块名与文件路径的对应关系——比如MyModule::MyClass必须对应my_module/my_class.rb（驼峰名转蛇形文件名，嵌套模块对应子文件夹）
• 写脚本批量扫描：用Parser gem解析所有.rb文件的AST，提取文件内定义的类/模块名，转成蛇形路径后和实际文件路径对比，直接输出不匹配项，省去手动翻几千个文件的麻烦
  核心思路示例：

  require "parser/current"
  Dir.glob("**/*.rb").each do |file|
    ast = Parser::CurrentRuby.parse(File.read(file))
    constants = []
    Parser::AST::Processor.new.tap do |processor|
      processor.define_method(:on_class) do |node|
        constants << node.children[0].children.join("::") if node.children[0].type == :const
      end
      processor.define_method(:on_module) do |node|
        constants << node.children[0].children.join("::") if node.children[0].type == :const
      end
      processor.process(ast)
    end
    expected_path = constants.first.underscore + ".rb"
    puts "不匹配：文件#{file} 预期路径#{expected_path}" unless file.end_with?(expected_path)
  end
  

2. 依赖与循环依赖检测 #

• 用ruby-dependency-analyzer工具扫描项目的require关系，生成可视化依赖图，循环依赖能直接定位
• 运行项目抓报错：如果出现NameError或加载顺序异常，跟着调用栈找互相require的文件对，就是循环依赖的源头

3. 用Zeitwerk自带工具预检查 #

• 写几行代码初始化Zeitwerk加载器，指定项目代码根目录，调用loader.check就能自动扫描并报告命名不匹配、未定义常量等问题：

  require "zeitwerk"
  loader = Zeitwerk::Loader.new
  loader.push_dir("lib") # 替换成你的项目代码根目录，比如src
  loader.check # 直接输出所有不符合规范的问题
  

二、一步步修正适配Zeitwerk #

1. 掰正命名与文件结构 #

• 重命名文件/文件夹：把驼峰常量名转成蛇形文件名，嵌套模块对应子文件夹——比如AdminDashboard改成admin_dashboard.rb，Shop::Order对应shop/order.rb
• 清理常量别名：如果有MyClass = MyOldClassName这类别名，要么改文件名匹配新常量名，要么直接删掉别名，Zeitwerk严格遵循路径对应常量的规则

2. 移除冗余require语句 #

• 逐步替换require/require_relative为Zeitwerk自动加载：先从独立模块开始改，再处理依赖复杂的部分
• 保留必要的require：比如非Ruby文件（.yml/.json等）、第三方库的显式引用，还有初始化阶段必须提前加载的代码

3. 解决循环依赖 #

• 重构代码：把两个文件互相依赖的公共逻辑抽成独立模块，让它们都依赖这个新模块，避免互相引用
• 延迟加载：把常量引用放到方法内部，别写在类的顶部，Zeitwerk会在用到常量时才加载，避开循环加载的冲突

三、Rails内置Zeitwerk检测工具的中文说明 #

这个工具是Rails官方提供的合规性检查器，核心是扫描项目代码，确保文件结构与常量命名符合Zeitwerk自动加载规则，核心逻辑可借鉴到非Rails项目中：

核心功能 #

• 检查所有自动加载目录下的文件，验证文件路径与定义的常量是否匹配
• 报告未被Zeitwerk自动加载覆盖的常量定义
• 检测可能导致加载错误的命名不一致问题

核心代码逻辑（翻译自原文件） #

# Rails Zeitwerk检查器，用于验证项目是否符合Zeitwerk自动加载规范
module Rails
  class ZeitwerkChecker
    def initialize(app = Rails.application)
      @app = app
    end

    # 执行完整检查并输出所有问题，返回是否无问题
    def check
      issues = []
      issues.concat(check_mismatches)
      issues.concat(check_unloaded_constants)
      issues.each { |issue| puts issue }
      issues.empty?
    end

    private
      # 检查文件路径与常量命名不匹配的情况
      def check_mismatches
        mismatches = []
        @app.config.autoload_paths.each do |path|
          Dir.glob("#{path}/**/*.rb").each do |file|
            relative_path = Pathname.new(file).relative_path_from(Pathname.new(path))
            expected_constant_name = relative_path.to_s.gsub(".rb", "").camelize
            # 解析文件中定义的常量，与预期名称对比
            constants_in_file = constants_defined_in(file)
            unless constants_in_file.include?(expected_constant_name)
              mismatches << "文件 #{file} 的路径对应预期常量 #{expected_constant_name}，但文件中定义的常量是 #{constants_in_file.join(', ')}"
            end
          end
        end
        mismatches
      end

      # 检查未被自动加载目录覆盖的常量
      def check_unloaded_constants
        unloaded = []
        ObjectSpace.each_object(Module) do |mod|
          next if mod.name.nil? || mod.name.empty?
          next if @app.config.autoload_paths.any? { |path| mod.name.underscore.start_with?(path.underscore) }
          unloaded << "常量 #{mod.name} 未被自动加载目录覆盖，可能无法被Zeitwerk自动加载"
        end
        unloaded
      end

      # 解析文件中定义的类/模块常量
      def constants_defined_in(file)
        # 简化实现，实际会用AST解析避免执行文件代码
        code = File.read(file)
        constants = []
        code.scan(/class\s+(\w+::)*\w+|module\s+(\w+::)*\w+/) do |matches|
          constants << matches.compact.join("::")
        end
        constants.uniq
      end
    end
end

非Rails项目适配建议 #

你可以提取这个工具的核心逻辑：比如文件路径转驼峰常量名的对比、扫描文件内常量的方法，修改成适配自己项目的版本——比如把@app.config.autoload_paths换成你项目的代码目录数组即可。

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