重新思考 Ruby 应用中的模块化设计

背景

在 Ruby 生态系统中，代码组织方式一直是开发者关注的焦点。作者近期发布了新的 Ruby Web 框架 Syntropy，该框架目前正运行在其个人网站上。Syntropy 的设计理念核心在于“基于文件的路由”（file-based routing），即应用程序的路由处理器（控制器）的源文件，根据其所属的 URL 命名空间进行组织和命名。

在深入探讨 Syntropy 的具体实现之前，有必要回顾一下 Ruby 领域最主流的框架 Rails 是如何处理代码组织和依赖加载的。Rails 依赖 Zeitwerk gem 来实现源文件的自动加载，这种机制通过目录结构来映射应用的命名空间（即类和模块），从而自动化依赖加载过程。然而，这种隐式依赖和全局状态的管理方式，在应用复杂度提升时暴露出了若干局限性，这也正是 Syntropy 试图通过显式依赖和模块化隔离来解决的问题。

核心内容

Rails 的自动加载机制及其局限

Rails 采用 Zeitwerk 进行自动加载，其核心逻辑是将应用的所有类和模块视为全局存在，并根据目录结构进行嵌套。这种设计带来了显著的优势：开发者无需显式编写 require 语句，任何对常量的引用都会触发自动加载；同时，Zeitwerk 还支持开发模式下的文件自动重载。

然而，这种基于全局常量和隐式依赖的模式存在两个主要缺点：

1. 文件与类的强耦合：Rails 遵循“一个文件一个类”的原则，类名必须与源文件路径严格匹配。如果移动源文件，必须同时重命名类以匹配新路径，这限制了代码重构的灵活性。
2. 全局状态的风险与隐式依赖：由于所有类和模块都是全局的，开发者可能会意外访问或修改不应触碰的类。更严重的是，依赖关系是隐式的，这种“错误的引用”往往难以察觉，导致未定义行为。例如，Web 应用中常用的单例对象（如数据库连接池、配置哈希等）若定义为全局常量，代码可能意外访问或改变其状态，引发难以调试的问题。

当应用规模扩大、源文件分散时，显式表达代码间的依赖关系对于理解应用结构和组件关系至关重要。此外，作者指出，接口不仅可以通过类和模块定义，还可以通过 proc/lambda（闭包）或其他单例对象来表达。显式引用这些对象（而非依赖全局常量）不仅简化了依赖注入（Dependency Injection）的实现，也极大地简化了测试过程。

Syntropy 的模块化设计

Syntropy 的设计哲学建立在两个核心原则之上：

1. 目录结构反映 URL 命名空间： 以博客应用为例，其目录结构如下：

   files           URLs
   =====           ====
   + app/
   + _lib/
     + storage.rb
   + _layout/
     + default.rb
     + index.rb    /
     + about.rb    /about
   + posts/
     + [id]/
       + index.rb  /posts/[id]
       + edit.rb   /posts/[id]/edit
     + index.rb    /posts
     + new.rb      /posts/new
   

   在此结构中，以 _ 开头的目录（如 _lib、_layout）被视为内部依赖，不会由 Syntropy 路由器暴露。控制器代码映射到具体的 URL 路径。

2. 依赖显式化： 在 Syntropy 中，加载任何内部依赖必须显式调用 import 函数。例如，app/posts/index.rb 的代码如下：

   # app/posts/index.rb
   @storage = import '/_lib/storage'
   @layout = import '/_layout/default'
   @template = @layout.apply { |posts:, **|
     posts.each { |post|
       article {
         h1 { a post.title, href: post.url }
         p post.body
       }
     }
   }
   export ->(req) {
     posts = @storage.get_all_posts
     req.respond_html(@template.render(posts:))
   }
   

   这里，@storage 作为模型接口，@layout 作为 Papercraft 布局模板接口，通过 import 显式引入。控制器最终通过 export 导出一个 lambda 函数，该函数接收 HTTP 请求，从 @storage 获取数据，并渲染 HTML 响应。

模块接口与导出机制

Syntropy 允许模块导出任何对象作为其接口，而不仅仅是类。

• 布局模块示例：

  # app/_layout/default.rb
  export template {
    html {
      head { ... }
      body {
        render_children
      }
    }
  }
  

  在此模块中，template（一个 Papercraft 模板）是模块的实际接口。每次 import 该模块时，都会获得相同的导出对象。

• 存储模块示例：

  # app/_lib/storage.rb
  export self
  def get_posts
    ...
  end
  ...
  

  在此模块中，模块自身作为单例对象导出，允许调用其方法：

  storage = import '/_lib/storage'
  storage.get_posts
  

显式加载的优势

这种加载方式带来了多重优势：

• 零副作用：模块代码加载对全局状态无副作用。所有常量和实例变量完全局限于模块上下文，不会泄漏到全局命名空间。
• 灵活的接口定义：模块接口可以是任何对象（包括单例），使得使用单例对象变得极其容易。
• 依赖清晰：显式的依赖关系使得理解代码各部分如何协作以及定位代码位置变得更加容易。
• 易于测试：由于模块完全自包含且不污染全局命名空间，可以更容易地进行独立单元测试。
• 简化代码重载：由于所有依赖在运行时都是已知的，系统可以追踪 import 调用。如果任何模块的底层文件发生变化，系统可以丢弃旧模块，重新加载新代码，并递归重载其所有反向依赖。

状态注入与测试

由于每个模块在加载时都在一个独立的匿名上下文中进行 eval，因此可以轻松地向模块注入状态。这对于注入环境哈希（包含应用配置）或其他应用关注点（如应用对象本身、底层的 UringMachine 实例或任何全局服务）特别有用。

这也简化了模块的单元测试。通过设置模块可用的实例变量来实现注入。例如，邮件模块可以访问配置如下：

# app/_lib/mailer.rb
require 'my_mailer'
export MyMailer.new(@env[:config][:smtp_server])

这里，@env 是在模块加载时注入的。在测试时，可以轻松注入自定义的 @env 对象。

关键要点

• Rails 的隐式依赖陷阱：Rails 依赖 Zeitwerk 实现自动加载，虽然方便，但导致依赖关系隐式化，且全局状态容易引发意外的副作用和难以调试的错误。
• Syntropy 的核心创新：采用“基于文件的路由”和“显式依赖注入”（通过 import 函数），取代了 Rails 的全局自动加载模式。
• 模块隔离性：Syntropy 的模块在独立的匿名上下文中执行，确保常量和实例变量不泄漏到全局命名空间，实现了真正的模块化隔离。
• 灵活的接口定义：模块不仅可以导出类，还可以导出 lambda、单例对象或其他任意对象，极大地提高了代码组织的灵活性。
• 开发体验优化：显式依赖使得代码结构更清晰，便于理解；同时，由于依赖关系明确，实现了更可靠、更简单的代码自动重载机制。
• 测试友好：通过上下文状态注入（如注入 @env），模块可以轻松进行独立单元测试，无需依赖全局状态或复杂的模拟对象。

意义与影响

Syntropy 对 Ruby 应用架构的重新思考，代表了从“约定