企业官网建设流程全解析

构建可维护的 Ruby 项目：多文件组织、require 加载机制与 Bundler 依赖管理实战指南

【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum

本篇文章围绕 Ruby 项目的工程化组织展开，系统讲解如何将一个项目拆分为多个文件并通过require/require_relative正确加载、如何用命名空间（module）避免代码冲突、如何理解 gem 与依赖声明，以及如何使用 Bundler 与Gemfile/Gemfile.lock锁定项目依赖版本。读完本文，你将掌握一套从目录结构、加载机制到依赖管理的完整 Ruby 项目搭建方案，并能配合.ruby-version与 Ruby LSP 让 VSCode 下的开发体验接近专业水准。

混乱、惯例与便利：为什么要拆分文件

回想一下你在 Foundations 阶段接触的项目：HTML、CSS、JS 各自存放在独立文件中，浏览器里之所以看起来"浑然一体"，是因为 HTML 通过<link>和<script>把它们串联了起来。这个思路同样适用于 Ruby。

把项目组织进多个文件有实实在在的好处，最核心的是让代码更加模块化（modular）：随着业务复杂度上升，将不同职责的代码隔离到不同文件，会大幅降低理解与调整的难度。那句老话——"每样东西都有它的位置，每样东西都在它的位置上"（A place for everything and everything in its place）——同样适用于软件项目。

对于 Ruby 项目，业界约定俗成的规则主要有两条：

• 一个类一个文件：每当你新建一个类，就应该为它单独创建一个文件。
• 所有 Ruby 源文件放入lib目录：这是 Ruby 社区最普遍的项目布局惯例，例如：

project_name ├── lib │ └── lovely_file_of_yours.rb └── main.rb

这种"入口文件 + lib 目录"的结构在后续课程中会反复出现，比如 RSpec 测试课程 就展示了lib/todo_list.rb存放业务代码、spec/存放测试代码的划分方式。

多文件加载：require_relative 与 require

代码拆分后，紧接着的问题就是：如何让一个文件中的代码能被另一个文件使用？考虑如下文件结构：

├── lib │ ├── sort │ │ ├── bogo_sort.rb │ │ ├── bubble_sort.rb │ │ └── merge_sort.rb │ └── sort.rb └── main.rb

Ruby 提供了两种主要加载方式：require_relative与require。两者都会执行目标文件，从而让你使用其中定义的内容；如果对同一个文件重复加载，第二次及以后不会再执行，调用会返回false。

require_relative：以"被加载文件自身"为参照

假设你的终端当前位于项目根目录（即存放main.rb的目录），main.rb与lib/sort.rb内容如下：

# main.rb require_relative 'lib/sort'

# lib/sort.rb require_relative 'sort/bubble_sort' require_relative 'sort/bogo_sort' require_relative 'sort/merge_sort'

官方文档对require_relative的定义是：

require_relative(string) → true or false

Ruby 尝试加载名为string的库，路径相对于包含该 require 语句的文件所在的目录。如果文件不存在则抛出LoadError。文件被加载时返回true，若此前已加载过则返回false。

关键在于"相对于包含该 require 语句的文件所在的目录"（relative to the directory containing the requiring file）。也就是说，无论你从哪个目录执行代码，require_relative都以写下这行代码的文件为起点解析路径。因此main.rb会进入lib查找sort（.rb扩展名可以省略），而sort.rb会进入sort目录查找那三个排序文件。

require：以"运行时的当前目录"为参照，并搜索 $LOAD_PATH

require的解析规则更复杂，官方文档的关键描述是：

如果特性是绝对路径（如以'/'开头），将直接按绝对路径加载。如果特性是显式相对路径（如以'./'或'../'开头），将相对于当前目录加载。否则，特性将在$LOAD_PATH列出的库目录中搜索。

绝对路径无需赘言；重点在于相对路径的差异：require以你运行代码时所在的目录为参照点。仍以上述项目为例（终端位于项目根目录）：

# main.rb require 'lib/sort'

# lib/sort.rb require 'sort/bubble_sort' require 'sort/bogo_sort' require 'sort/merge_sort'

直接运行会报错——因为'lib/sort'不是显式相对路径，Ruby 不会把它当作相对路径处理，而去$LOAD_PATH里也找不到，于是抛出LoadError。改成显式相对路径后：

# main.rb require './lib/sort'

# lib/sort.rb require './sort/bubble_sort' require './sort/bogo_sort' require './sort/merge_sort'

此时main.rb中的require './lib/sort'可以正常工作，但sort.rb里的require './sort/bubble_sort'会再次报错——因为它不是从sort.rb的角度解析，而是仍然从main.rb所在的当前目录去找./sort/bubble_sort，自然找不到。

再看$LOAD_PATH的部分：

# main.rb require 'csv' require_relative 'lib/sort'

require 'csv'会在 Ruby 的全局变量$LOAD_PATH中查找csv.rb，该变量默认包含 Ruby 标准库路径。require会自动尝试.rb等扩展名而无需显式声明；如果在$LOAD_PATH中没有找到，它还会继续在已安装的 gem中查找（这正是后面要讲的 RubyGems 的功劳）。

由此可以得出社区通行的约定：require_relative用于加载自己的代码，require用于加载外部的东西——比如项目依赖的 gem。

实战示例：多文件项目如何串联

借助这种加载机制，你无需把整个应用的代码塞进一个文件。假设文件结构如下：

├── lib │ ├── flight.rb │ ├── hotel.rb │ └── airport.rb └── main.rb

各文件内容：

# lib/airport.rb class Airport def introduce puts "I'm at the airport!" end end

# lib/flight.rb class Flight def introduce puts "I'm on the flight!" end end

# lib/hotel.rb class Hotel def introduce puts "I'm at the hotel!" end end

# main.rb require_relative 'lib/airport' require_relative 'lib/flight' require_relative 'lib/hotel' Airport.new.introduce #=> I'm at the airport! Flight.new.introduce #=> I'm on the flight! Hotel.new.introduce #=> I'm at the hotel!

这样就不必在airport.rb里同时定义Flight和Hotel类。习惯做法是在最顶层的文件（如这里的main.rb）集中 require 所有文件，让其他人只要拿到main.rb就能获得完整代码。

需要注意两点加载时的边界行为：

• 局部变量不会被加载：如果airport.rb里定义了局部变量coolest_airports，在main.rb中访问它会直接报错；
• 常量会被加载：模块、类等常量定义在 require 后可以在其他文件中正常访问。

命名空间：为什么要把代码包进 module

一个必须牢记的事实是：所有被 require 进来的代码都处于同一个命名空间。如果不同文件里定义了同名的方法、模块或类，后加载的定义会覆盖先加载的定义。例如你和朋友都写了同名方法（为简化，假设文件都在同一目录）：

# not_so_green.rb def food_opinion(food) "#{food} is awesome!" end

# scheals.rb def food_opinion(food) "#{food} is awful!" end

# main.rb require_relative 'not_so_green' require_relative 'scheals' puts food_opinion('Cereal') #=> Cereal is awful!

因为food_opinion被定义了两次，最后一次定义胜出。为了避免代码被意外覆盖，Ruby 开发者会把代码包裹在模块（module）中，利用模块获得命名空间的隔离效果：

# not_so_green.rb module NotSoGreen def self.food_opinion(food) "#{food} is awesome!" end end

# scheals.rb module Scheals def self.food_opinion(food) "#{food} is awful!" end end

# main.rb require_relative 'not_so_green' require_relative 'scheals' puts NotSoGreen.food_opinion('Cereal') #=> Cereal is awesome! puts Scheals.food_opinion('Marmite') #=> Marmite is awful! puts food_opinion('Cereal') #=> Errors out—there's no longer a free floating food_opinion method to use.

使用模块限定名（NotSoGreen.food_opinion/Scheals.food_opinion）后，两个同名方法互不干扰，而顶层不再存在游离的food_opinion方法。在后续编写多类项目（如 Tic Tac Toe 项目、Mastermind 项目）时，这一约定能有效避免类与方法名冲突。

Gem 与依赖：使用别人的代码

学会组织自己的文件后，就该学习如何使用他人的文件了。

Gem就是别人写好的、打包好的 Ruby 工具库——本质上就是一些代码。其中一部分 gem 属于 Ruby 标准库，但绝大多数需要单独安装。如果你在项目中使用某个 gem，它就成了你的依赖（dependency）——你的代码依赖它才能正常运行。有些依赖只在特定场景下使用，例如只有开发环境或测试环境才需要的 gem 集合。

很多 gem 又依赖其他 gem，而且它们所依赖的版本可能各不相同。你当然可以手动完成安装、更新、解决版本冲突的全过程，但 Ruby 社区早已有了趁手的工具。

RubyGems：gem 的安装通道

RubyGems自 Ruby 1.9 起就是 Ruby 标准库的一部分，用来把 gem 安装到你的电脑上。还记得前面提到require会在已安装的 gem 中查找文件吗？那正是 RubyGems 的工作。更有趣的是，RubyGems 本身也是一个 gem！

动手试一试。在一个名为colorful的目录中创建main.rb：

require 'colorize' puts 'Red goes faster!'.colorize(:red) puts "I'm blue da ba dee da ba di!".colorize(:blue) puts "It ain't easy bein' green...".colorize(:green)

运行ruby main.rb期待看到颜色……结果却是一个LoadError。没错——你需要先安装这个 gem：

gem install colorize

执行后，你的系统就能访问Colorizegem 了。但这只是你自己的系统；别人想运行你的代码，也得各自gem install。一个两个倒还好，可如果项目里有几十个 gem 呢？如何保证大家下载到的版本完全一致？这就要请出Bundler了——它本身也是 RubyGems 旗下的一个 gem，只是独立发布。

Bundler：声明依赖并锁定版本

Bundler 允许你声明项目需要哪些 gem，精确到版本。其他人拿到这份声明——一个名为Gemfile的简单文件——就可以通过一条bundle install快速安装全部 gem。

由于gem install是全局的，你还需要一种方式，让运行时只使用Gemfile中声明的那些特定版本。方法是使用bundle exec前缀，后面跟上你想执行的命令——最常见的就是bundle exec ruby foo.rb。

让我们确保任何人想运行我们的脚本都能如愿：

bundle init # 在当前工作目录创建一个默认 Gemfile bundle add colorize # 把 colorize gem 加入 Gemfile 并执行 bundle install

这两条命令生成了两个文件：Gemfile和Gemfile.lock。来看它们的内容：

# Gemfile # frozen_string_literal: true source "https://rubygems.org" # gem "rails" gem "colorize", "~> 1.1"

# Gemfile.lock GEM remote: https://rubygems.org/ specs: colorize (1.1.0) PLATFORMS ruby x86_64-linux # This might be different for you if you're using a different CPU and OS. DEPENDENCIES colorize (~> 1.1) BUNDLED WITH 2.5.4

可以看到，Gemfile包含了从哪里获取 gem（source行）以及需要哪些 gem（gem声明行）。Gemfile.lock则记录了上一次成功运行应用的环境快照：Bundler 会依据它安装相同版本的 gem，即使Gemfile本身允许安装更新的版本。

版本约束：读懂 "~> 1.1"

Gemfile中的"~> 1.1"是一种版本约束，更准确地说叫悲观约束（pessimistic constraint），它建立在**语义化版本（semantic versioning）**的基础上。语义化版本号由三部分组成：

1. 第一位是major（主版本）；
2. 第二位是minor（次版本）；
3. 第三位（如果存在）是patch（补丁号）。

主版本升级可能破坏旧版本的兼容性——比如改动方法名；次版本可以新增、修改功能，但不能破坏兼容性；补丁号则用于不影响兼容性的 bug 修复。

因此，只要 gem 维护者遵守语义化版本规范，你就可以信赖悲观约束不会让项目拿到一个可能破坏应用的版本。gem "colorize", "~> 1.1"等价于gem "colorize", ">= 1.1", "< 2.0"。

Gemfile.lock的作用可以概括为：记录能够运行你的应用的上一个环境。即使Gemfile允许安装更新的版本，Bundler 也会用Gemfile.lock安装相同的版本，从而保证"在我机器上能跑"在别人机器上同样能跑。

.ruby-version：声明目标 Ruby 版本

除了依赖，运行代码的人还需要知道项目的目标 Ruby 版本。一条命令就能做到：

rbenv local 3.2.2

它会创建一个.ruby-version文件，内容即声明的版本号（此处为3.2.2）。你可以先用rbenv versions查看本机通过 rbenv 安装的 Ruby 版本列表，挑一个实际存在的版本试运行该命令。

许多工具都会读取.ruby-version来判断项目使用的 Ruby 版本：例如 rbenv 将不再使用全局（global）Ruby 版本，Ruby LSP的 VSCode 扩展也会随之调整行为。

VSCode 中的 Ruby LSP：让编辑器感知你的项目

在课程更早的阶段，你可能被要求在选择Don't show again选项后忽略Ruby LSP关于"找不到 lock 文件"的提示，也可能见过与RuboCop相关的报错。这些报错的出现是有原因的：Ruby LSP 需要项目的Gemfile/Gemfile.lock才能确定要加载哪些工具与版本，而 RuboCop 作为规范检查工具，也应当作为项目依赖出现在Gemfile中。

在下一课（linting_and_rubocop）中会详细讲解 RuboCop 的安装与配置。届时你将看到这样的完整工作流：先用 Bundler 在项目里声明并安装 RuboCop（bundle exec rubocop保证运行的是项目本地版本），再通过 Ruby LSP 与 VSCode 集成，在编辑过程中持续获得即时反馈、自动修复（quickfix）与悬停提示。把上面这些要素——Gemfile、Gemfile.lock、.ruby-version、RuboCop 依赖——逐一就位后，你的项目就完成了"专业级"的初始化，Ruby LSP 的所有能力（含 RuboCop 集成）都会自动生效。

值得一提的是，这种"Gemfile声明 +bundle install安装 +Gemfile.lock锁定"的流程在整个课程中会反复出现：RSpec 测试课程 里就是先创建Gemfile写入gem 'rspec', '3.10'，再运行bundle install生成Gemfile.lock，从而保证测试环境在所有机器上一致。

知识自检

• 为什么要把代码拆分到多个文件？参见上文"混乱、惯例与便利"一节——核心是模块化，便于维护与理解。
• 如何让不同文件中的代码互相可用？通过require_relative（相对被加载文件）与require（相对当前目录或$LOAD_PATH/ 已装 gem）实现。
• 为什么要用模块包裹代码？所有 require 进来的代码共享同一命名空间，模块可以隔离同名方法、类，避免后者覆盖前者。
• 什么是 gem？别人写好的、打包的 Ruby 工具库，是代码复用的基本单元。
• 如何安装 gem？运行gem install <gem_name>（如gem install colorize）。
• Bundler 的用途是什么？声明项目所需的 gem 及其版本（Gemfile），并通过bundle install一键安装。
• 为什么要用bundle exec？gem 安装是全局的，bundle exec能确保运行时只使用Gemfile中声明的版本。
• Gemfile与Gemfile.lock各有什么用？Gemfile声明依赖来源与约束；Gemfile.lock锁定上一成功环境的精确版本，保证跨机器一致性。

至此，你已经掌握了从"单文件脚本"迈向"可维护工程"的关键三步：用require_relative组织自己的文件、用 module 隔离命名空间、用 Bundler 管理外部依赖。以此为起点，后续学习 RuboCop（linting_and_rubocop）与 RSpec 测试（rspec_part_one_basics）时，你会发现整个工具链都建立在本文这套项目组织与依赖管理的基础之上。

【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum