Rails 8.2 railties 核心变更深度拆解：bin/rails query、Rails.app 配置 API 与生成器/控制台现代化

本文以 Rails 当前仓库的 railties/CHANGELOG.md 为主体脉络，结合 railties 与 activesupport 的真实源码，系统梳理 Rails 8.2 框架层（railties）的核心演进：面向日常开发的新命令与配置读取 API、控制台会话体验升级、以及 rails new 生成模板与测试/部署链路的现代化。读完本文，你可以掌握 bin/rails query 的完整用法、Rails.app.envs/dotenvs/creds/revision 的读取规则与组合顺序，理解 --no-banner、--query-cache 等控制台选项背后的执行模型，并知晓新生成应用的默认配置与文件布局变化。

背景：这份 CHANGELOG 记录了什么

railties 是 Ruby on Rails 的"应用引导层"，负责把各个独立框架（Active Record、Action Pack、Active Job 等）装配成可以启动的 Web 应用——应用生成器、bin/rails 命令、中间件栈、常量加载与重载都归属其中。当前仓库的 railties/CHANGELOG.md 记录的是 Rails 8.2 开发周期内 railties 的变更条目。

从版本号文件 RAILS_VERSION（内容为 8.2.0.alpha）以及 railties/lib/rails/gem_version.rb（MAJOR = 8, MINOR = 2, TINY = 0, PRE = "alpha"）可以确认，本仓库正处于 Rails 8.2 的 alpha 阶段，因此文中的新特性均属于尚未发布的开发版能力，引用时需注意版本前提。本文件底部提示"更早的变更见 8-1-stable 分支"，意味着这里的内容是相对 Rails 8.1 之后新累积的条目。

以下按主题把条目重组为八类，并为每类补充源码级佐证。

1. 新增 bin/rails query：面向脚本与调试的只读查询命令

这是本文件中最具重量级的新命令。此前在 Rails 里跑查询要么借助 bin/rails runner，要么在 console 中手敲；而新的 bin/rails query 把"执行表达式 / 原生 SQL + 输出结构化结果"做成了专门命令。文件给出了五个典型用法：

$ bin/rails query "Account.where(plan: 'premium').limit(10)"
$ bin/rails query --sql "SELECT COUNT(*) FROM accounts"
$ bin/rails query schema accounts
$ bin/rails query models
$ bin/rails query explain "Account.where(plan: 'premium')"

其实现位于 railties/lib/rails/commands/query/query_command.rb，从源码可以梳理出它的关键设计：

• 表达式分发：perform 方法把参数首词与 schema、models、explain 匹配后进入不同子流程（见 query_command.rb），其余情况一律走普通查询 run_query。
• 只读保证：连接默认优先走读取副本角色。with_readonly_connection_for 会先探测 :reading 角色是否可用（connected_to(role: :reading)），可用则使用副本；否则退化为 while_preventing_writes 锁住写操作（见 query_command.rb）。显式指定数据库时通过 --db/--database 选项（如 primary_replica），同样套上 while_preventing_writes。
• 表达式与 SQL 两种模式：默认把输入当作 Active Record 表达式在顶层绑定上 eval（因此 Account.where(...) 这类模型表达式可直接运行）；加 --sql 则作为原生 SQL 交给 connection.select_all。
• 自动分页与限制：--page（默认 1）与 --per（默认 100、上限 10000）。对原生 SQL，若去掉注释后不含 LIMIT，会自动追加 LIMIT per+1 并配合 OFFSET，用多取一行来判断"是否还有更多数据"（见 query_command.rb）；对 Relation 表达式，仅在未显式 limit 时才补充分页。
• JSON 输出与元信息：结果统一以 JSON 返回，包含 columns、rows，以及 meta 里的 row_count、query_time_ms、page、per_page、has_more 和实际执行的 sql（见 query_command.rb），非常便于被外部脚本或运维工具解析。
• 子命令用途：
  • query schema：无参数时列出所有表名，跟表名则输出该表的列（名称/类型/可空/默认值）、索引、枚举（若存在对应模型）与关联信息（见 query_command.rb）；
  • query models：应用 eager load 后列出所有非抽象、有表名的模型，含 table_name 与格式化后的关联数组（见 query_command.rb）；
  • query explain：对表达式先求 to_sql 再执行 EXPLAIN，支持与 --sql 组合直接 EXPLAIN 原生 SQL。
• 支持从标准输入读取：当表达式为 -，或没有传表达式但 stdin 不是 TTY 时，会读取 stdin 全部内容作为查询（见 query_command.rb），方便管道调用。

这一命令把以往散落在 runner、console、psql 中的操作收敛成一个"可读、只读、可脚本化"的入口，适合故障排查、数据核查与 CI 中的数据库冒烟检查。

2. Rails.app 与新一代配置读取体系：envs / dotenvs / creds

2.1 Rails.app 成为 Rails.application 的便捷别名

条目原文指出新增 Rails.app 作为 Rails.application 的别名，特别有利于在应用代码里书写 Rails.app.credentials 这类嵌套访问。在 railties 的生成模板中已经可以看到它的实际应用：例如新应用的 config.ru 中直接 run Rails.app（见 railties/lib/rails/generators/rails/app/templates/config.ru.tt），config/storage.yml 模板里也大量使用 Rails.app.credentials.dig(...) 占位（见 railties/lib/rails/generators/rails/app/templates/config/storage.yml.tt）。

2.2 Rails.app.envs：符号化访问 ENV

envs 提供基于符号的查找，并为"必填项"与"可选项"提供显式方法（实现与 credentials 一致，可被 creds 组合）。CHANGELOG 给出的对照示例：

Rails.app.envs.require(:db_password)          # ENV.fetch("DB_PASSWORD")
Rails.app.envs.require(:aws, :access_key_id)  # ENV.fetch("AWS__ACCESS_KEY_ID")
Rails.app.envs.option(:cache_host)            # ENV["CACHE_HOST"]
Rails.app.envs.option(:cache_host, default: "cache-host-1")     # ENV.fetch("CACHE_HOST", "cache-host-1")
Rails.app.envs.option(:cache_host, default: -> { HostProvider.cache }) # ENV.fetch("CACHE_HOST") { HostProvider.cache }

注意嵌套符号 :aws, :access_key_id 会映射成 AWS__ACCESS_KEY_ID（双下划线连接命名空间），源码见 railties/lib/rails/application.rb，其底层类是 Active Support 新增的 activesupport/lib/active_support/env_configuration.rb。

2.3 Rails.app.dotenvs：统一读取 .env

dotenvs 用与 envs/credentials 相同的接口暴露 .env 文件中的变量，并额外支持 ${VAR} 变量插值与 $(command) 命令插值（见 railties/lib/rails/application.rb）。其实现基于 activesupport/lib/active_support/dot_env_configuration.rb。新应用的 env 模板（见 railties/lib/rails/generators/rails/app/templates/env.tt）注释也明确写道：本地环境变量可通过 Rails.app.creds 读取，且该文件默认不纳入 git。

2.4 Rails.app.creds：ENV + .env + 加密凭据的组合视图

creds 是这三层配置的统一入口。源码（见 railties/lib/rails/application.rb）表明：在 development 环境中它由 envs + dotenvs + credentials 三层组合而成，其他环境则组合 envs + credentials。CHANGELOG 的示例：

Rails.app.creds.require(:db_host)                  # ENV.fetch("DB_HOST") || Rails.app.credentials.require(:db_host)
Rails.app.creds.require(:aws, :access_key_id)      # ENV.fetch("AWS__ACCESS_KEY_ID") || Rails.app.credentials.require(:aws, :access_key_id)
Rails.app.creds.option(:cache_host)                # ENV["CACHE_HOST"] || Rails.app.credentials.option(:cache_host)
Rails.app.creds.option(:cache_host, default: "cache-host-1")       # ENV["CACHE_HOST"] || Rails.app.credentials.option(:cache_host) || "cache-host-1"
Rails.app.creds.option(:cache_host, default: -> { "cache-host-1" }) # ENV["CACHE_HOST"] || Rails.app.credentials.option(:cache_host) || "cache-host-1"

由于 creds 支持写入自定义组合配置（attr_writer :creds），你还可以把其他后端插在 ENV 与加密凭据之间，例如文件注释中演示的：

Rails.app.creds = ActiveSupport::CombinedConfiguration.new(
  Rails.app.envs, OnePasswordConfiguration.new, Rails.app.credentials
)

底层组合机制见 activesupport/lib/active_support/combined_configuration.rb。这套 API 让"密钥从环境变量迁移到加密凭据（或反向）"不再需要改代码——配置读取从"到处 ENV.fetch + credentials.dig"收敛为统一的 require/option 模型。

3. Rails.app.revision：标准化的部署标识

CHANGELOG 记录了两个条目：其一新增 Rails.app.revision 用于错误上报、监控与缓存键中的版本标识；其二是让它在检查 REVISION 文件或 git 之前优先读取 ENV["REVISION"]。组合后的解析优先级为：ENV["REVISION"] → 应用根目录下的 REVISION 文件 → 从本地 git 仓库提取。相关源码见 railties/lib/rails/application.rb。

用法与自定义回退如下（来自 CHANGELOG）：

Rails.app.revision # => "3d31d593e6cf0f82fa9bd0338b635af2f30d627b"

当文件与 git 都不适用时，可在应用配置中直接注入：

# config/application.rb
module MyApp
  class Application < Rails::Application
    config.revision = ENV["GIT_SHA"]
  end
end

config.revision= 实际上透传给 Rails.application.revision=（见 railties/lib/rails/application/configuration.rb）。该值还被 /rails/info 页面当作 "Application revision" 属性展示（见 railties/lib/rails/info.rb），错误上报工具也可直接引用，避免各应用自行拼 sha 导致的不一致。

4. bin/rails console 体验升级：横幅、提示、Executor 与查询缓存

CHANGELOG 中 console 相关条目密集，合起来描述了一轮控制台会话模型的完整调整：

4.1 --no-banner 与 Rails 风格启动横幅

新增 --no-banner 选项用于一次性/脚本化会话中隐藏启动横幅（此前只能通过 .irbrc 里设置 IRB.conf[:SHOW_BANNER] = false）：

bin/rails console --no-banner

同时，启动时默认展示 Rails 风味的横幅——包含小 logo、Rails/Ruby 版本、关于 app/reload! 等控制台辅助方法的小贴士，以及 Rails.root。原因如文件所述：rails console 绕过了 IRB 的正常启动路径，所以直接 irb 会出现的横幅从未在 Rails console 中出现。若想隐藏轮换小贴士，可设环境变量 RAILS_TIPS=false。控制台启动还会打印一行 help 提示（"Type 'help' for help."）。这些逻辑集中在 railties/lib/rails/commands/console/console_command.rb：banner 选项默认 true（见第 94-95 行），startup_lines 依 sandbox 与否生成不同文案并追加 HELP_HINT（见第 7、34-42 行）。

4.2 默认关闭 Active Record 查询缓存，可按会话开启

条目指出：使用 executor 时，console 默认关闭 Active Record 查询缓存（此前是默认开启），需要时传 --query-cache 在本次会话启用。源码中 perform 在包裹 executor 且未给 --query-cache 时会遍历所有连接池并逐个 disable_query_cache!（见 railties/lib/rails/commands/console/console_command.rb）。这对调试"每次查询都走数据库"的真实行为很有帮助。

4.3 Executor 包裹与 reload!

console 默认被 Rails Executor 包裹（与 runner 行为对齐），可用 -w / --skip_executor 关闭；reload! 在有 executor 时会一并重置它。这两点让 console 会话下的代码执行语义（如 ActiveSupport::Executor 驱动的查询缓存、to_prepare 钩子等）与请求环境保持一致。

4.4 sandbox 相关提醒

顺带一提，bin/rails console 依旧支持 -s/--sandbox（默认 nil，且当 config.disable_sandbox 为真时会拒绝启动并报错），这些选项均定义于 railties/lib/rails/commands/console/console_command.rb。

5. 测试运行器：缺失目录不再抛 LoadError，改为"零测试"

条目修复了一个真实的 CI 首推失败场景：生成的 GitHub Actions workflow 会执行 bin/rails test:system，但全新应用并不存在 test/system 目录，导致首次 push 即报 cannot load such file -- <app>/test/system (LoadError)。同样受影响的还有 test:channels、test:jobs、test:mailboxes、test:units、test:functionals、test:generators。现在的行为是：当 bin/rails test:* 指向的目录不存在时，报告 0 个测试而不是抛错。

从生成模板看，生成到新应用的 CI 配置确实把 bin/rails test:system 作为独立步骤执行（见 railties/lib/rails/generators/rails/app/templates/github/ci.yml.tt），因此该修复直接决定了"rails new 后第一推"是否可绿。这一行为修正让各种 test:folder 命令对"有没有这个测试目录"更加宽容，应用可以安全地在 CI 里统一执行全套命令。

6. rails new 生成模板与默认配置的变化

这一组条目影响每一个新生成的应用：

6.1 默认开启 Ruby frozen string literals

新应用会生成一个启用 frozen string literals 的 config/bootsnap.rb（模板位于 railties/lib/rails/generators/rails/app/templates/config/bootsnap.rb.tt）。注意作用范围：只影响应用自身代码，不影响依赖。也可对依赖一并开启以减少对象分配，但部分老 gem 可能不兼容；若在应用中关闭该特性，需同步调整自动生成的 .rubocop.yml（其默认假设已开启 frozen string literals）。

6.2 PWA 脚手架加入离线回退页

新应用现在包含 app/views/pwa/offline.html.erb 模板（见 railties/lib/rails/generators/rails/app/templates/app/views/pwa/offline.html.erb），并在 config/routes.rb 中提供一条注释掉的 get "offline" 路由；service worker 模板也附带了一段注释示例，演示如何缓存并离线提供该页面。对于默认自带 manifest + service worker 的 Rails 8.x 应用而言，离线体验终于有官方脚手架可循。

6.3 生成器自动探测 JavaScript 包管理器

Rails 生成器不再硬编码 yarn，而是通过工程内的 lockfile 自动识别 bun、pnpm、npm 或 yarn，保证 rails new 产物与所选前端工具链一致。

6.4 依赖与运行环境相关细节

• .node-version 条件生成文件更新到 22.21.1；
• libvips 会条件性加入生成的 ci.yml（图片处理相关任务需要时）；
• rails new 生成的 GitHub Actions workflow 默认设为只读权限（最小权限原则，防写 GITHUB_TOKEN）；
• 新增 --update 选项到 bin/bundler-audit 脚本（用于更新漏洞数据库）。脚本与相关模板位于 railties 的生成器/命令资源目录中。

6.5 config.asset_host 默认从环境变量读取

新配置语义使 CDN 接入不再需要改代码：

config.asset_host = ENV["CDN_HOST"]

由此静态资源可直接经 CDN 分发。与此相关的资源类优化还包括：若 config.action_dispatch.x_sendfile_header 为 nil，则不再把 Rack::Sendfile 塞进中间件栈（它是 noop，留着无意义）；config.rake_eager_load 在生成的测试环境配置中与 config.eager_load 对齐，保证 CI 里 rake 任务先加载 :environment 再跑测试时 eager load 行为一致。

6.6 app:update 与新框架默认值文件清理

当 config.load_defaults 已经指向当前 Rails 版本时，app:update 会移除残留的 new_framework_defaults 文件，避免升级后的应用仍保留已并入默认行为的冗余配置。仓库中与当前版本对应的模板是 railties/lib/rails/generators/rails/app/templates/config/initializers/new_framework_defaults_8_2.rb.tt，可据此对照 8.2 新增的默认行为开关。

7. 命令健壮性、生成器与开发期内部路由

• rails plugin 子命令校验：此前 rails plugin foo bar 会静默忽略非法子命令 "foo"，直接创建一个名为 "bar" 的插件；现在会打印错误并以状态码 1 退出（修复 #57430）。
• 认证生成器跳过重复迁移：当 User 模型已存在时，不再生成 CreateUsers 迁移。
• 去除 token 迁移的重复唯一索引：避免同一字段被建两次唯一索引。
• 开发期欢迎路由去重：内部欢迎页面路由在路由 reload 时不再被重复注册。
• Chromium devtools 内部路由：新增一条开发环境内部路由响应 Chromium 系浏览器的 devtools GET 请求，方便把 app 目录直接挂接为浏览器工作区。
• /rails/info/routes 状态持久化：路由表页面的搜索关键词与结果在页面刷新之间得以保留。

8. 路由加载、重载器与基础设施修正

8.1 mounted route helpers 触发懒加载

此前命名 URL helper（如 users_path）已经具备按需加载路由的能力，但挂载型 helper（main_app 以及引擎挂载代理）只有在路由绘制执行 mount 时才被定义——因此在 console 或测试中率先调用它们会抛 NoMethodError。本次变更让这些 helper 同样触发路由懒加载，而不是等别处先画好路由。这属于对路由加载时序的收敛性修复，其机制与 railties/lib/rails/application/routes_reloader.rb 负责的路由重载逻辑相关。

8.2 RoutesReloader 尊重自定义 file_watcher

Rails::Application::RoutesReloader 改为使用 Rails.application.config.file_watcher 配置的文件监视器，意味着应用自定义的 watcher（例如基于事件驱动的文件监听）在路由文件监视上同样生效。

8.3 app.reloaders 升级为 ReloadersCollection

app.reloaders 现在返回一个 ReloadersCollection：当调用 clear 或 delete 移除某个 reloader 时，会先调用其 deactivate 方法，使其有机会清理外部状态（如注销已注册的回调）。该集合的说明文档明确写在这层意图（见 railties/lib/rails/application/reloaders_collection.rb），应用初始化时即以它为 reloader 容器（见 railties/lib/rails/application.rb）。

8.4 加载、过滤与错误上报

• 环境文件存在性检查：Rails::Application 若无法加载任何环境文件会直接抛错，避免应用在错误的配置下静默启动。
• 不过滤不存在的 i18n 路径：此前初始化会过滤掉不存在的 i18n 路径，这对拥有大量翻译文件的应用产生负面性能影响，现改为不过滤。
• BacktraceCleaner 优化：大部分位于应用根目录正下方的路径不再被静默过滤，调试时错误堆栈更完整。
• rails stats 扩展注册：新增 Rails::CodeStatistics.register_extension("txt")，可让 rails stats 统计自定义扩展名的源码文件。
• 结构化弃用事件：当 config.active_support.deprecation 设为 :notify 时，Rails 弃用会发布结构化事件，便于接入观测后端。
• rake 任务异常上报：通过 Rails 命令运行 rake 任务时，未处理的异常会交给 Error Reporter，与请求环境中的错误上报路径对齐。

小结：8.2 railties 的三个走向

把 railties/CHANGELOG.md 的条目串起来看，Rails 8.2 的 railties 工作大致有三个方向：

1. 把"读配置、读数据"做成显式且安全的 API——Rails.app.envs/dotenvs/creds 统一了多来源配置的符号化读取，Rails.app.revision 标准化部署标识，bin/rails query 则把数据库探查收敛为只读、JSON 化、可脚本化的命令；
2. 提升 console 与测试的开发反馈质量——启动横幅、help 提示、--no-banner、按会话开关查询缓存、Executor 包裹，以及 test:* 对缺失目录的宽容处理，都直接作用于日常开发循环；
3. 让"新生成应用"更接近生产默认——frozen string literals、PWA 离线页、包管理器探测、CDN 友好配置、CI 最小权限与 libvips 条件依赖等，缩短从 rails new 到"可上线"的距离。

需要重申的是，上述能力均来自当前仓库 8.2.0.alpha（见 RAILS_VERSION 与 railties/lib/rails/gem_version.rb）的快照，正式版发布时细节仍可能调整；其中部分源码属于 nodoc 内部实现（如 QueryCommand、ReloadersCollection），其行为以各版本官方文档为准。对照阅读 railties/CHANGELOG.md 与本仓库源码，是跟踪 Rails 每轮框架演进最直接的途径。