Ruby on Rails 7.1 發行說明

1 升級到 Rails 7.1

如果您要升級現有的應用程式，在開始之前最好要有良好的測試涵蓋範圍。如果您尚未升級到 Rails 7.0，也應該先升級，並確保您的應用程式仍如預期執行，然後再嘗試更新到 Rails 7.1。在升級 Ruby on Rails 指南中提供了升級時需要注意的事項清單。

2 項主要功能

2.1 為新的 Rails 應用程式產生 Dockerfiles

預設 Docker 支援給新的 Rails 應用程式。在產生新的應用程式時，Rails 現在會在應用程式中包含與 Docker 相關的檔案。

這些檔案用作在生產環境中使用 Docker 部署 Rails 應用程式的基礎設定。重要的是要注意，這些檔案並非用於開發目的。

以下是如何使用這些 Docker 檔案建置和執行 Rails 應用程式的快速範例

$ docker build -t app .
$ docker volume create app-storage
$ docker run --rm -it -v app-storage:/rails/storage -p 3000:3000 --env RAILS_MASTER_KEY=<your-config-master-key> app

您也可以從這個 Docker 映像啟動主控台或執行器

$ docker run --rm -it -v app-storage:/rails/storage --env RAILS_MASTER_KEY=<your-config-master-key> app console

對於那些想要建立多平台映像（例如，適用於 AMD 或 Intel 部署的 Apple Silicon）並將其推送到 Docker Hub 的人，請執行下列步驟

$ docker login -u <your-user>
$ docker buildx create --use
$ docker buildx build --push --platform=linux/amd64,linux/arm64 -t <your-user/image-name> .

此增強功能簡化了部署程序，提供了一個便捷的起點，讓您的 Rails 應用程式可以在生產環境中啟動並執行。

2.2 新增 `ActiveRecord::Base.normalizes`

ActiveRecord::Base.normalizes 宣告屬性標準化。當屬性被指定或更新時，會套用標準化，而標準化值將會持續到資料庫。此標準化也會套用至查詢方法的對應關鍵字引數，允許使用非標準化值來查詢記錄。

例如

class User < ActiveRecord::Base
  normalizes :email, with: -> email { email.strip.downcase }
  normalizes :phone, with: -> phone { phone.delete("^0-9").delete_prefix("1") }
end

user = User.create(email: " [email protected]\n")
user.email                  # => "[email protected]"

user = User.find_by(email: "\t[email protected] ")
user.email                  # => "[email protected]"
user.email_before_type_cast # => "[email protected]"

User.where(email: "\t[email protected] ").count         # => 1
User.where(["email = ?", "\t[email protected] "]).count # => 0

User.exists?(email: "\t[email protected] ")         # => true
User.exists?(["email = ?", "\t[email protected] "]) # => false

User.normalize_value_for(:phone, "+1 (555) 867-5309") # => "5558675309"

2.3 新增 `ActiveRecord::Base.generates_token_for`

ActiveRecord::Base.generates_token_for 定義為特定目的產生權杖。產生的權杖可能會過期，也可以嵌入記錄資料。在使用權杖擷取記錄時，將會比較權杖中的資料和記錄中的目前資料。如果兩者不符，權杖將被視為無效，就像它已經過期一樣。

以下是一個實作單次使用密碼重設權杖的範例

class User < ActiveRecord::Base
  has_secure_password

  generates_token_for :password_reset, expires_in: 15.minutes do
    # `password_salt` (defined by `has_secure_password`) returns the salt for
    # the password. The salt changes when the password is changed, so the token
    # will expire when the password is changed.
    password_salt&.last(10)
  end
end

user = User.first
token = user.generate_token_for(:password_reset)

User.find_by_token_for(:password_reset, token) # => user

user.update!(password: "new password")
User.find_by_token_for(:password_reset, token) # => nil

2.4 新增 `perform_all_later` 以一次排入多個工作

Active Job 中的 perform_all_later 方法，旨在簡化同時排入多個工作的流程。這個強大的新增功能讓您可以有效率地排入工作，而不會觸發回呼。當您需要一次排入大量工作時，這特別有用，因為它減少了與佇列資料儲存區進行多次往返的開銷。

以下是您可以如何利用 perform_all_later 的方法

# Enqueueing individual jobs
ActiveJob.perform_all_later(MyJob.new("hello", 42), MyJob.new("world", 0))

# Enqueueing an array of jobs
user_jobs = User.pluck(:id).map { |id| UserJob.new(user_id: id) }
ActiveJob.perform_all_later(user_jobs)

透過使用 perform_all_later，您可以最佳化您的工作排入流程，並利用提升的效率，特別是在處理大量工作時。值得注意的是，對於支援新的 enqueue_all 方法的佇列轉接器，例如 Sidekiq 轉接器，排入流程會進一步透過 push_bulk 最佳化。

請注意，這個新方法會引入一個獨立的事件 enqueue_all.active_job，而且不會使用現有的 enqueue.active_job 事件。這可確保準確追蹤和報告大量排入的流程。

2.5 複合主鍵

複合主鍵現在在資料庫和應用程式層級都獲得支援。Rails 能夠直接從架構衍生這些鍵。這個功能對於多對多關係和其他複雜資料模型特別有益，因為單一欄位不足以唯一識別記錄。

Active Record 中查詢方法產生的 SQL（例如 #reload、#update、#delete）將包含複合主鍵的所有部分。像 #first 和 #last 等方法會在 ORDER BY 陳述式中使用完整的複合主鍵。

query_constraints 巨集可用作「虛擬主鍵」，以達成相同的行為，而無須修改資料庫架構。範例

class TravelRoute < ActiveRecord::Base
  query_constraints :origin, :destination
end

類似地，關聯接受 query_constraints: 選項。此選項用作複合外來鍵，設定用於存取關聯記錄的欄位清單。

範例

class TravelRouteReview < ActiveRecord::Base
  belongs_to :travel_route, query_constraints: [:travel_route_origin, :travel_route_destination]
end

2.6 為 `Trilogy` 導入轉接器

已導入新的轉接器，以促進 Trilogy（相容於 MySQL 的資料庫用戶端）與 Rails 應用程式的無縫整合。現在，Rails 應用程式可透過設定 config/database.yml 檔案，選擇納入 Trilogy 功能。例如

development:
  adapter: trilogy
  database: blog_development
  pool: 5

或者，可使用 DATABASE_URL 環境變數進行整合

ENV['DATABASE_URL'] # => "trilogy://127.0.0.1/blog_development?pool=5"

2.7 加入 `ActiveSupport::MessagePack`

ActiveSupport::MessagePack 是一個序列化器，與 msgpack 寶石整合。ActiveSupport::MessagePack 可序列化 msgpack 支援的基本 Ruby 型別，以及其他多種型別，例如 Time、ActiveSupport::TimeWithZone 和 ActiveSupport::HashWithIndifferentAccess。與 JSON 和 Marshal 相比，ActiveSupport::MessagePack 可縮小負載大小並提升效能。

ActiveSupport::MessagePack 可用作訊息序列化器

config.active_support.message_serializer = :message_pack

# Or individually:
ActiveSupport::MessageEncryptor.new(secret, serializer: :message_pack)
ActiveSupport::MessageVerifier.new(secret, serializer: :message_pack)

作為 Cookie 序列化器

config.action_dispatch.cookies_serializer = :message_pack

以及作為快取序列化器

config.cache_store = :file_store, "tmp/cache", { serializer: :message_pack }

# Or individually:
ActiveSupport::Cache.lookup_store(:file_store, "tmp/cache", serializer: :message_pack)

2.8 導入 `config.autoload_lib` 和 `config.autoload_lib_once` 以進行增強自動載入

已導入新的設定方法 config.autoload_lib(ignore:)。此方法用於透過包含 lib 目錄（預設不包含）來增強應用程式的自動載入路徑。此外，config.autoload_lib(ignore: %w(assets tasks)) 會為新的應用程式產生。

當從 config/application.rb 或 config/environments/*.rb 呼叫時，此方法會將 lib 目錄新增至 config.autoload_paths 和 config.eager_load_paths。請務必注意，此功能不適用於引擎。

為了確保彈性，可以使用 ignore 關鍵字引數指定 lib 目錄中不應由自動載入程式管理的子目錄。例如，您可以將 assets、tasks 和 generators 等目錄傳遞至 ignore 引數，將其排除在外

config.autoload_lib(ignore: %w(assets tasks generators))

config.autoload_lib_once 方法類似於 config.autoload_lib，不同之處在於它將 lib 新增至 config.autoload_once_paths。

請參閱自動載入指南中的更多詳細資訊

2.9 Active Record API for general async queries

Active Record API 已進行重大強化，擴充其非同步查詢支援。此強化功能旨在更有效率地處理速度較慢的查詢，特別著重於聚合 (例如 count、sum 等) 和傳回單一記錄或任何非 Relation 的方法。

新的 API 包含下列非同步方法

async_count
async_sum
async_minimum
async_maximum
async_average
async_pluck
async_pick
async_ids
async_find_by_sql
async_count_by_sql

以下是如何使用其中一個方法 async_count 以非同步方式計算已發布文章數量的簡要範例

# Synchronous count
published_count = Post.where(published: true).count # => 10

# Asynchronous count
promise = Post.where(published: true).async_count # => #<ActiveRecord::Promise status=pending>
promise.value # => 10

這些方法允許以非同步方式執行這些操作，這可以大幅提升特定類型資料庫查詢的效能。

2.10 Allow templates to set strict `locals`

推出新功能，允許範本設定明確的 locals。此強化功能在傳遞變數至範本時提供更佳的控制和清晰度。

預設情況下，範本會接受任何 locals 作為關鍵字引數。不過，現在您可以透過在範本檔案開頭新增 locals 魔術註解，定義範本應接受哪些 locals。

以下是它的運作方式

<%# locals: (message:) -%>
<%= message %>

您也可以為這些區域設定預設值

<%# locals: (message: "Hello, world!") -%>
<%= message %>

如果您想要完全停用區域變數，您可以這樣做

<%# locals: () %>

2.11 新增 `Rails.application.deprecators`

新的 Rails.application.deprecators 方法會傳回應用程式內受管理的棄用項集合，並讓您可以輕鬆新增和擷取個別棄用項

Rails.application.deprecators[:my_gem] = ActiveSupport::Deprecation.new("2.0", "MyGem")
Rails.application.deprecators[:other_gem] = ActiveSupport::Deprecation.new("3.0", "OtherGem")

集合的組態設定會影響集合中的所有棄用項。

Rails.application.deprecators.debug = true

Rails.application.deprecators[:my_gem].debug
# => true

Rails.application.deprecators[:other_gem].debug
# => true

在某些情況下，您可能想要將特定程式碼區塊的所有棄用項警告設為靜音。有了棄用項集合，您可以在區塊內輕鬆將所有棄用項警告設為靜音

Rails.application.deprecators.silence do
  Rails.application.deprecators[:my_gem].warn    # No warning (silenced)
  Rails.application.deprecators[:other_gem].warn # No warning (silenced)
end

2.12 支援 JSON `response.parsed_body` 的模式比對

當 ActionDispatch::IntegrationTest 測試區塊呼叫 JSON 回應的 response.parsed_body 時，其酬載將可以使用非區分存取。這能與 Ruby 的模式比對整合，以及內建的 Minitest 模式比對支援

get "/posts.json"

response.content_type         # => "application/json; charset=utf-8"
response.parsed_body.class    # => Array
response.parsed_body          # => [{"id"=>42, "title"=>"Title"},...

assert_pattern { response.parsed_body => [{ id: 42 }] }

get "/posts/42.json"

response.content_type         # => "application/json; charset=utf-8"
response.parsed_body.class    # => ActiveSupport::HashWithIndifferentAccess
response.parsed_body          # => {"id"=>42, "title"=>"Title"}

assert_pattern { response.parsed_body => [{ title: /title/i }] }

2.13 擴充 `response.parsed_body` 以使用 Nokogiri 分析 HTML

擴充 ActionDispatch::Testing 模組以支援將 HTML response.body 的值分析成 Nokogiri::HTML5::Document 執行個體

get "/posts"

response.content_type         # => "text/html; charset=utf-8"
response.parsed_body.class    # => Nokogiri::HTML5::Document
response.parsed_body.to_html  # => "<!DOCTYPE html>\n<html>\n..."

新加入的 Nokogiri 模式比對支援，以及內建的 Minitest 模式比對支援提供了對 HTML 回應的結構和內容進行測試斷言的機會

get "/posts"

html = response.parsed_body # => <html>
                            #      <head></head>
                            #        <body>
                            #          <main><h1>Some main content</h1></main>
                            #        </body>
                            #     </html>

assert_pattern { html.at("main") => { content: "Some main content" } }
assert_pattern { html.at("main") => { content: /content/ } }
assert_pattern { html.at("main") => { children: [{ name: "h1", content: /content/ }] } }

2.14 引入 `ActionView::TestCase.register_parser`

擴充 ActionView::TestCase 以支援將檢視部分所呈現的內容解析成已知的結構。預設定義 rendered_html 以將 HTML 解析成 Nokogiri::XML::Node，並定義 rendered_json 以將 JSON 解析成 ActiveSupport::HashWithIndifferentAccess

test "renders HTML" do
  article = Article.create!(title: "Hello, world")

  render partial: "articles/article", locals: { article: article }

  assert_pattern { rendered_html.at("main h1") => { content: "Hello, world" } }
end

test "renders JSON" do
  article = Article.create!(title: "Hello, world")

  render formats: :json, partial: "articles/article", locals: { article: article }

  assert_pattern { rendered_json => { title: "Hello, world" } }
end

若要將呈現的內容解析成 RSS，請註冊呼叫 RSS::Parser.parse

register_parser :rss, -> rendered { RSS::Parser.parse(rendered) }

test "renders RSS" do
  article = Article.create!(title: "Hello, world")

  render formats: :rss, partial: article, locals: { article: article }

  assert_equal "Hello, world", rendered_rss.items.last.title
end

若要將呈現的內容解析成 Capybara::Simple::Node，請使用呼叫 Capybara.string 重新註冊 :html 解析器

register_parser :html, -> rendered { Capybara.string(rendered) }

test "renders HTML" do
  article = Article.create!(title: "Hello, world")

  render partial: article

  rendered_html.assert_css "main h1", text: "Hello, world"
end

3 Railties

請參閱變更記錄以取得詳細變更內容。

3.1 移除

移除已棄用的 bin/rails secrets:setup 指令。
移除預設 X-Download-Options 標頭，因為它只會被 Internet Explorer 使用。

3.2 已棄用

已棄用 Rails.application.secrets 的使用。
已棄用 secrets:show 和 secrets:edit 指令，請改用 credentials。
已棄用 Rails::Generators::Testing::Behaviour，請改用 Rails::Generators::Testing::Behavior。

3.3 顯著變更

新增 sandbox_by_default 選項，以預設在沙盒模式中啟動 rails 主控台。
新增新的語法，以支援根據行範圍篩選測試。
新增 DATABASE 選項，在執行 rails railties:install:migrations 指令以複製遷移時，可指定目標資料庫。
新增對 rails new --javascript 產生器的 Bun 支援。
```
$ rails new my_new_app --javascript=bun
```
新增顯示測試執行器中速度較慢測試的功能。

新增 capture_broadcasts 測試輔助程式，用於擷取區塊中廣播的所有訊息。
新增 Redis pub/sub 適配器功能，在 Redis 連線中斷時自動重新連線。
新增命令回呼 before_command、after_command 和 around_command 至 ActionCable::Connection::Base。

5 Action Pack

請參閱變更日誌以取得詳細變更內容。

5.1 移除

移除 Request#content_type 上已棄用的行為。
移除將單一值指定給 config.action_dispatch.trusted_proxies 的已棄用功能。
移除系統測試的已棄用 poltergeist 和 webkit (capybara-webkit) 驅動程式註冊。

5.2 已棄用

已棄用 config.action_dispatch.return_only_request_media_type_on_content_type。
已棄用 AbstractController::Helpers::MissingHelperError。
已棄用 ActionDispatch::IllegalStateError。
已棄用權限政策指令 speaker、vibrate 和 vr。
已棄用 config.action_dispatch.show_exceptions 的 true 和 false 值，建議改用 :all、:rescuable 或 :none。

5.3 顯著變更

新增 exclude? 方法至 ActionController::Parameters。它是 include? 方法的反向。
新增 ActionController::Parameters#extract_value 方法，允許從參數中提取序列化值。
新增使用自訂邏輯儲存和擷取 CSRF 令牌的功能。
新增系統測試螢幕擷取輔助程式的 html 和 screenshot 關鍵字參數。

6 Action View

請參閱變更日誌以取得詳細變更內容。

6.1 移除

移除已棄用常數 ActionView::Path。
移除將實例變數作為局部變數傳遞給部分的已棄用支援。

6.2 已棄用

6.3 顯著變更

check_box_tag 和 radio_button_tag 現在接受 checked 作為關鍵字參數。
新增 picture_tag 輔助函式以產生 HTML <picture> 標籤。

simple_format 輔助函式現在處理 :sanitize_options 功能，允許為 sanitizing 程序新增額外選項。

simple_format("<a target=\"_blank\" href=\"http://example.com\">Continue</a>", {}, { sanitize_options: { attributes: %w[target href] } })
# => "<p><a target=\"_blank\" href=\"http://example.com\">Continue</a></p>"

已棄用 config.action_mailer.preview_path。
已棄用透過 :args 關鍵字參數將參數傳遞給 assert_enqueued_email_with。現在支援 :params 關鍵字參數，因此請使用它來傳遞參數。

7.3 顯著變更

新增 config.action_mailer.preview_paths 以支援多個預覽路徑。
在測試輔助函式中新增 capture_emails 以擷取在區塊中傳送的所有電子郵件。
新增 deliver_enqueued_emails 至 ActionMailer::TestHelper 以傳送所有排隊的電子郵件工作。

8 Active Record

請參閱變更日誌以取得詳細變更。

8.1 移除

移除對 ActiveRecord.legacy_connection_handling 的支援。
移除已棄用的 ActiveRecord::Base 設定存取器
移除對 configs_for 上的 :include_replicas 的支援。請改用 :include_hidden。
移除已棄用的 config.active_record.partial_writes。
移除已棄用的 Tasks::DatabaseTasks.schema_file_type。
移除 PostgreSQL 結構轉儲中的 --no-comments 旗標。

8.2 已棄用

已棄用 #remove_connection 上的 name 參數。
已棄用 check_pending!，改用 check_all_pending!。
已棄用 add_foreign_key 的 deferrable: true 選項，改用 deferrable: :immediate。
棄用 TestFixtures#fixture_path，改用 TestFixtures#fixture_paths。
棄用從 Base 到 connection_handler 的委派。
棄用 config.active_record.suppress_multiple_database_warning。
棄用在 SQL 字串範本中使用 ActiveSupport::Duration 作為內插綁定參數。
棄用 all_connection_pools，並使 connection_pool_list 更明確。
棄用 read_attribute(:id)，如果主鍵不是 :id，則傳回主鍵。
棄用 #merge 上的 rewhere 參數。
棄用使用 alias_attribute 將非屬性設定別名。

8.3 顯著變更

新增 TestFixtures#fixture_paths 以支援多個固定路徑。
使用 has_secure_password 時新增 authenticate_by。
新增 update_attribute! 至 ActiveRecord::Persistence，其類似於 update_attribute，但當 before_* 回呼擲回 :abort 時會引發 ActiveRecord::RecordNotSaved。
允許使用別名屬性搭配 insert_all/upsert_all。
新增 :include 選項至 add_index。
新增 #regroup 查詢方法，作為 .unscope(:group).group(fields) 的簡寫。
新增對 SQLite3 介面自動填入欄位和自訂主鍵的支援。
新增 SQLite3 資料庫連線的現代化、高效能預設值。

允許使用欄位組語法指定 where 子句。

Topic.where([:title, :author_name] => [["The Alchemist", "Paulo Coelho"], ["Harry Potter", "J.K Rowling"]])

自動產生的索引名稱現在限制在 62 位元組內，符合 MySQL、PostgreSQL 和 SQLite 的預設索引名稱長度限制。
推出 Trilogy 資料庫用戶端介面。
新增 ActiveRecord.disconnect_all! 方法，可立即關閉所有池中的所有連線。
新增 PostgreSQL 遷移指令，用於列舉變更名稱、新增值和變更值。
新增 ActiveRecord::Base#id_value 別名，用於存取記錄 id 欄位的原始值。
新增 enum 的驗證選項。

9 Active Storage

請參閱變更日誌，以取得詳細變更。

9.1 移除

移除 Active Storage 設定中已棄用的無效預設內容類型。
移除已棄用的 `ActiveStorage::Current#host` 和 `ActiveStorage::Current#host=` 方法。
移除指派到附件集合時的已棄用行為。現在會取代集合，而不是附加到集合。
移除附件關聯中的已棄用 `purge` 和 `purge_later` 方法。

9.2 已棄用

9.3 顯著變更

ActiveStorage::Analyzer::AudioAnalyzer 現在會在輸出 `metadata` hash 中輸出 `sample_rate` 和 `tags`。
新增選項，在附件上呼叫 `preview` 或 `representation` 方法時使用預先定義的變體。
宣告變體時新增 `preprocessed` 選項，以預先處理變體。

新增銷毀 Active Storage 變體的功能。

User.first.avatar.variant(resize_to_limit: [100, 100]).destroy

新增對 `LengthValidator`s `:in` / `:within` 選項的無限範圍支援。
```
validates_length_of :first_name, in: ..30
```

新增對 `inclusivity/exclusivity` 驗證器的無開始範圍支援。

validates_inclusion_of :birth_date, in: -> { (..Date.today) }

validates_exclusion_of :birth_date, in: -> { (..Date.today) }

新增對 `has_secure_password` 的密碼挑戰支援。設定時，驗證密碼挑戰是否與持續的 `password_digest` 相符。

允許驗證器接受沒有記錄參數的 lambda。

# Before
validates_comparison_of :birth_date, less_than_or_equal_to: ->(_record) { Date.today }

# After
validates_comparison_of :birth_date, less_than_or_equal_to: -> { Date.today }

11 Active Support

請參閱變更日誌，以取得詳細變更內容。

11.1 移除

移除 `Enumerable#sum` 的已棄用覆寫。
移除已棄用的 `ActiveSupport::PerThreadRegistry`。
移除已棄用的選項，傳遞格式給 `Array`、`Range`、`Date`、`DateTime`、`Time`、`BigDecimal`、`Float` 和 `Integer` 中的 `#to_s`。
移除已棄用的 ActiveSupport::TimeWithZone.name 覆寫。
移除已棄用的 active_support/core_ext/uri 檔案。
移除已棄用的 active_support/core_ext/range/include_time_with_zone 檔案。
移除 ActiveSupport::SafeBuffer 將物件隱含轉換為 String 的功能。
移除已棄用的支援，當提供非 Digest::UUID 定義的常數作為 namespace ID 時，會產生不正確的 RFC 4122 UUID。

11.2 已棄用

棄用 config.active_support.disable_to_s_conversion。
棄用 config.active_support.remove_deprecated_time_with_zone_name。
棄用 config.active_support.use_rfc4122_namespaced_uuids。
棄用 SafeBuffer#clone_empty。
棄用單例 ActiveSupport::Deprecation 的使用。
棄用使用 Dalli::Client 實例初始化 ActiveSupport::Cache::MemCacheStore。
棄用 Notification::Event 的 #children 和 #parent_of? 方法。

移除 QueAdapter。

12.2 已棄用

12.3 值得注意的變更

新增 perform_all_later 以一次排程多個工作。
新增 --parent 選項至工作產生器，以指定工作的父類別。
新增 after_discard 方法至 ActiveJob::Base，以便在工作即將被捨棄時執行回呼。
新增支援，以記錄背景工作排程呼叫者。

將 X-Forwarded-To 地址新增至收件者。
將 bounce_now_with 方法新增至 ActionMailbox::Base，以在不經過郵件佇列的情況下傳送退信電子郵件。

意見回饋

我們鼓勵您協助提升本指南的品質。

如果您發現任何錯字或事實錯誤，請貢獻您的力量。首先，您可以閱讀我們的文件貢獻部分。

您也可能會發現不完整或過時的內容。請務必新增任何遺漏的說明文件。請務必先查看 Edge Guides，以驗證問題是否已在主分支中修正。查看 Ruby on Rails 指南準則以了解風格和慣例。

如果您發現需要修正的內容，但無法自行修補，請開啟問題。

最後，歡迎在官方 Ruby on Rails 論壇上針對 Ruby on Rails 文件進行任何討論。

章節

意見回饋