Rails on Rack · Ruby on Rails 指南

# Rails on Rack 本文介紹 Rails 和 Rack 的集成，以及與其他 Rack 組件的配合。讀完本文，你將學到： * 如何在 Rails 程序中使用中間件； * Action Pack 內建的中間件； * 如何編寫中間件； ### Chapters 1. [Rack 簡介](#rack-%E7%AE%80%E4%BB%8B) 2. [Rails on Rack](#rails-on-rack) * [Rails 程序中的 Rack 對象](#rails-%E7%A8%8B%E5%BA%8F%E4%B8%AD%E7%9A%84-rack-%E5%AF%B9%E8%B1%A1) * [`rails server`](#rails-server) * [`rackup`](#rackup) 3. [Action Dispatcher 中間件](#action-dispatcher-%E4%B8%AD%E9%97%B4%E4%BB%B6) * [查看使用的中間件](#%E6%9F%A5%E7%9C%8B%E4%BD%BF%E7%94%A8%E7%9A%84%E4%B8%AD%E9%97%B4%E4%BB%B6) * [設置中間件](#%E8%AE%BE%E7%BD%AE%E4%B8%AD%E9%97%B4%E4%BB%B6) * [內部中間件](#%E5%86%85%E9%83%A8%E4%B8%AD%E9%97%B4%E4%BB%B6) 4. [參考資源](#%E5%8F%82%E8%80%83%E8%B5%84%E6%BA%90) * [學習](#%E5%AD%A6%E4%B9%A0) * [理解中間件](#%E7%90%86%E8%A7%A3%E4%B8%AD%E9%97%B4%E4%BB%B6) 閱讀本文之前需要了解 Rack 協議及相關概念，如中間件、URL 映射和 `Rack::Builder`。 ### 1 Rack 簡介 Rack 為使用 Ruby 開發的網頁程序提供了小型模塊化，適應性極高的接口。Rack 盡量使用最簡單的方式封裝 HTTP 請求和響應，為服務器、框架和二者之間的軟件（中間件）提供了統一的 API，只要調用一個簡單的方法就能完成一切操作。 * [Rack API 文檔](http://rack.rubyforge.org/doc/) 詳細解說 Rack 不是本文的目的，如果不知道 Rack 基礎知識，可以閱讀“[參考資源](#resources)”一節。 ### 2 Rails on Rack #### 2.1 Rails 程序中的 Rack 對象 `ApplicationName::Application` 是 Rails 程序中最主要的 Rack 程序對象。任何支持 Rack 的服務器都應該使用 `ApplicationName::Application` 對象服務 Rails 程序。`Rails.application` 也指向 `ApplicationName::Application` 對象。 #### 2.2 `rails server` `rails server` 命令會創建 `Rack::Server` 對象并啟動服務器。 `rails server` 創建 `Rack::Server` 實例的方法如下： ``` Rails::Server.new.tap do |server| require APP_PATH Dir.chdir(Rails.application.root) server.start end ``` `Rails::Server` 繼承自 `Rack::Server`，使用下面的方式調用 `Rack::Server#start` 方法： ``` class Server < ::Rack::Server def start ... super end end ``` `Rails::Server` 加載中間件的方式如下： ``` def middleware middlewares = [] middlewares << [Rails::Rack::Debugger] if options[:debugger] middlewares << [::Rack::ContentLength] Hash.new(middlewares) end ``` `Rails::Rack::Debugger` 基本上只在開發環境中有用。下表說明了加載的各中間件的用途： | 中間件 | 用途 | | --- | --- | | `Rails::Rack::Debugger` | 啟用調試功能 | | `Rack::ContentLength` | 計算響應的長度，單位為字節，然后設置 HTTP Content-Length 報頭 | #### 2.3 `rackup` 如果想用 `rackup` 代替 `rails server` 命令，可以在 Rails 程序根目錄下的 `config.ru` 文件中寫入下面的代碼： ``` # Rails.root/config.ru require ::File.expand_path('../config/environment', __FILE__) use Rails::Rack::Debugger use Rack::ContentLength run Rails.application ``` 然后使用下面的命令啟動服務器： ``` $ rackup config.ru ``` 查看 `rackup` 的其他選項，可以執行下面的命令： ``` $ rackup --help ``` ### 3 Action Dispatcher 中間件 Action Dispatcher 中的很多組件都以 Rack 中間件的形式實現。`Rails::Application` 通過 `ActionDispatch::MiddlewareStack` 把內部和外部的中間件組合在一起，形成一個完整的 Rails Rack 程序。在 Rails 中，`ActionDispatch::MiddlewareStack` 的作用和 `Rack::Builder` 一樣，不過前者更靈活，也為滿足 Rails 的需求加入了更多功能。 #### 3.1 查看使用的中間件 Rails 提供了一個 rake 任務，用來查看使用的中間件： ``` $ rake middleware ``` 在新建的 Rails 程序中，可能會輸出如下結果： ``` use Rack::Sendfile use ActionDispatch::Static use Rack::Lock use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware:0x000000029a0838> use Rack::Runtime use Rack::MethodOverride use ActionDispatch::RequestId use Rails::Rack::Logger use ActionDispatch::ShowExceptions use ActionDispatch::DebugExceptions use ActionDispatch::RemoteIp use ActionDispatch::Reloader use ActionDispatch::Callbacks use ActiveRecord::Migration::CheckPending use ActiveRecord::ConnectionAdapters::ConnectionManagement use ActiveRecord::QueryCache use ActionDispatch::Cookies use ActionDispatch::Session::CookieStore use ActionDispatch::Flash use ActionDispatch::ParamsParser use Rack::Head use Rack::ConditionalGet use Rack::ETag run MyApp::Application.routes ``` 這里列出的各中間件在“[內部中間件](#internal-middleware-stack)”一節有詳細介紹。 #### 3.2 設置中間件 Rails 在 `application.rb` 或 `environments/<environment>.rb` 文件中提供了一個簡單的設置項 `config.middleware`，可以在middleware堆棧中添加，修改和刪除中間件。 ##### 3.2.1 添加新中間件使用下面列出的任何一種方法都可以添加新中間件： * `config.middleware.use(new_middleware, args)`：把新中間件添加到列表末尾； * `config.middleware.insert_before(existing_middleware, new_middleware, args)`：在 `existing_middleware` 之前添加新中間件； * `config.middleware.insert_after(existing_middleware, new_middleware, args)`：在 `existing_middleware` 之后添加新中間件； ``` # config/application.rb # Push Rack::BounceFavicon at the bottom config.middleware.use Rack::BounceFavicon # Add Lifo::Cache after ActiveRecord::QueryCache. # Pass { page_cache: false } argument to Lifo::Cache. config.middleware.insert_after ActiveRecord::QueryCache, Lifo::Cache, page_cache: false ``` ##### 3.2.2 替換中間件使用 `config.middleware.swap` 可以替換middleware堆棧中的中間件： ``` # config/application.rb # Replace ActionDispatch::ShowExceptions with Lifo::ShowExceptions config.middleware.swap ActionDispatch::ShowExceptions, Lifo::ShowExceptions ``` ##### 3.2.3 刪除中間件在程序的設置文件中加入下面的代碼： ``` # config/application.rb config.middleware.delete "Rack::Lock" ``` 現在查看所用的中間件，會發現 `Rack::Lock` 不在輸出結果中。 ``` $ rake middleware (in /Users/lifo/Rails/blog) use ActionDispatch::Static use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware:0x00000001c304c8> use Rack::Runtime ... run Blog::Application.routes ``` 如果想刪除會話相關的中間件，可以這么做： ``` # config/application.rb config.middleware.delete "ActionDispatch::Cookies" config.middleware.delete "ActionDispatch::Session::CookieStore" config.middleware.delete "ActionDispatch::Flash" ``` 刪除瀏覽器相關的中間件： ``` # config/application.rb config.middleware.delete "Rack::MethodOverride" ``` #### 3.3 內部中間件 Action Controller 的很多功能都以中間件的形式實現。下面解釋個中間件的作用。 **`Rack::Sendfile`**：設置服務器上的 X-Sendfile 報頭。通過 `config.action_dispatch.x_sendfile_header` 選項設置。 **`ActionDispatch::Static`**：用來服務靜態資源文件。如果選項 `config.serve_static_assets` 為 `false`，則禁用這個中間件。 **`Rack::Lock`**：把 `env["rack.multithread"]` 旗標設為 `false`，程序放入互斥鎖中。 **`ActiveSupport::Cache::Strategy::LocalCache::Middleware`**：在內存中保存緩存，非線程安全。 **`Rack::Runtime`**：設置 X-Runtime 報頭，即執行請求的時長，單位為秒。 **`Rack::MethodOverride`**：如果指定了 `params[:_method]` 參數，會覆蓋所用的請求方法。這個中間件實現了 PUT 和 DELETE 方法。 **`ActionDispatch::RequestId`**：在響應中設置一個唯一的 X-Request-Id 報頭，并啟用 `ActionDispatch::Request#uuid` 方法。 **`Rails::Rack::Logger`**：請求開始時提醒日志，請求完成后寫入日志。 **`ActionDispatch::ShowExceptions`**：補救程序拋出的所有異常，調用處理異常的程序，使用特定的格式顯示給用戶。 **`ActionDispatch::DebugExceptions`**：如果在本地開發，把異常寫入日志，并顯示一個調試頁面。 **`ActionDispatch::RemoteIp`**：檢查欺騙攻擊的 IP。 **`ActionDispatch::Reloader`**：提供“準備”和“清理”回調，協助開發環境中的代碼重新加載功能。 **`ActionDispatch::Callbacks`**：在處理請求之前調用“準備”回調。 **`ActiveRecord::Migration::CheckPending`**：檢查是否有待運行的遷移，如果有就拋出 `ActiveRecord::PendingMigrationError` 異常。 **`ActiveRecord::ConnectionAdapters::ConnectionManagement`**：請求處理完成后，清理活躍的連接，除非在發起請求的環境中把 `rack.test` 設為 `true`。 **`ActiveRecord::QueryCache`**：啟用 Active Record 查詢緩存。 **`ActionDispatch::Cookies`**：設置請求的 cookies。 **`ActionDispatch::Session::CookieStore`**：負責把會話存儲在 cookies 中。 **`ActionDispatch::Flash`**：設置 Flash 消息的鍵。只有設定了 `config.action_controller.session_store` 選項時才可用。 **`ActionDispatch::ParamsParser`**：把請求中的參數出入 `params`。 **`ActionDispatch::Head`**：把 HEAD 請求轉換成 GET 請求，并處理。 **`Rack::ConditionalGet`**：添加對“條件 GET”的支持，如果頁面未修改，就不響應。 **`Rack::ETag`**：為所有字符串類型的主體添加 ETags 報頭。ETags 用來驗證緩存。設置 Rack 時可使用上述任意一個中間件。 ### 4 參考資源 #### 4.1 學習 * [Rack 官網](http://rack.github.io) * [Rack 簡介](http://chneukirchen.org/blog/archive/2007/02/introducing-rack.html) * [Ruby on Rack #1 - Hello Rack!](http://m.onkey.org/ruby-on-rack-1-hello-rack) * [Ruby on Rack #2 - The Builder](http://m.onkey.org/ruby-on-rack-2-the-builder) #### 4.2 理解中間件 * [Railscast 介紹 Rack 中間件的視頻](http://railscasts.com/episodes/151-rack-middleware) ### 反饋歡迎幫忙改善指南質量。如發現任何錯誤，歡迎修正。開始貢獻前，可先行閱讀[貢獻指南：文檔](http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation)。翻譯如有錯誤，深感抱歉，歡迎 [Fork](https://github.com/ruby-china/guides/fork) 修正，或至此處[回報](https://github.com/ruby-china/guides/issues/new)。文章可能有未完成或過時的內容。請先檢查 [Edge Guides](http://edgeguides.rubyonrails.org) 來確定問題在 master 是否已經修掉了。再上 master 補上缺少的文件。內容參考 [Ruby on Rails 指南準則](ruby_on_rails_guides_guidelines.html)來了解行文風格。最后，任何關于 Ruby on Rails 文檔的討論，歡迎到 [rubyonrails-docs 郵件群組](http://groups.google.com/group/rubyonrails-docs)。