升级Rails 7后含模块名片段的类出现未定义常量错误

问题场景 #

升级Rails 7后，gem中出现大量「未定义常量」错误，以下是两个典型案例：

• 模型文件 app/models/my_gem/api/irr_item.rb 原代码：

module MyGem
  module Api
    class IrrItem < MyGem::Api::ApplicationRecord
    # ...
    end
  end
end

将类名中的Irr改为全大写IRR后，错误消失：

module MyGem
  module Api
    class IRRItem < MyGem::Api::ApplicationRecord
    # ...
    end
  end
end

• 路由约束文件 app/constraints/graphiql_route_constraint.rb 原代码：

class GraphiqlRouteConstraint
  # ...
end

将类名中的ql改为全大写QL后，问题解决：

class GraphiQLRouteConstraint
  # ...
end

原因解析 #

核心原因是Rails 7默认启用了Zeitwerk作为常量加载器，它对常量名与文件名的映射规则比旧版经典加载器更严格，尤其针对包含缩写的命名：

• Zeitwerk会自动将驼峰式常量名拆分为可能的命名空间（比如IrrItem会被解析为Irr::Item，GraphiqlRouteConstraint会被解析为Graphiql::RouteConstraint）
• 如果代码中没有定义Irr或Graphiql这类模块，就会抛出「未定义常量」错误
• 当缩写词全大写时（比如IRR、QL），Zeitwerk会将其视为一个完整的命名单元，不会进行拆分，因此能正确匹配对应的蛇形文件名（irr_item.rb对应IRRItem，graphiql_route_constraint.rb对应GraphiQLRouteConstraint）

另外，若代码中确实存在IRR模块，Zeitwerk的拆分逻辑会优先匹配已存在的命名空间，导致原类名无法被正确识别，全大写缩写则可以避免这种冲突。

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