本教學假設你已具備閱讀 Rails 入門指南 的基本 Rails 知識。
1 建立 Rails 應用程式
首先,讓我們使用 rails new
指令建立一個簡單的 Rails 應用程式。
我們將使用這個應用程式來玩玩並探索本指南中描述的所有指令。
如果你還沒有安裝 rails gem,你可以輸入 gem install rails
來安裝。
1.1 rails new
我們將傳遞給 rails new
指令的第一個參數是應用程式名稱。
$ rails new my_app
create
create README.md
create Rakefile
create config.ru
create .gitignore
create Gemfile
create app
...
create tmp/cache
...
run bundle install
對於如此微小的指令,Rails 會設定看起來非常龐大的東西!現在我們有了完整的 Rails 目錄結構,其中包含我們開箱即用執行簡單應用程式所需的所有程式碼。
如果您希望略過產生某些檔案或略過某些函式庫,您可以將下列任何引數附加到您的 rails new
指令
引數 | 說明 |
---|---|
--skip-git |
略過 git init、.gitignore 和 .gitattributes |
--skip-docker |
略過 Dockerfile、.dockerignore 和 bin/docker-entrypoint |
--skip-keeps |
略過原始碼控制 .keep 檔案 |
--skip-action-mailer |
略過 Action Mailer 檔案 |
--skip-action-mailbox |
略過 Action Mailbox gem |
--skip-action-text |
略過 Action Text gem |
--skip-active-record |
略過 Active Record 檔案 |
--skip-active-job |
略過 Active Job |
--skip-active-storage |
略過 Active Storage 檔案 |
--skip-action-cable |
略過 Action Cable 檔案 |
--skip-asset-pipeline |
略過 Asset Pipeline |
--skip-javascript |
略過 JavaScript 檔案 |
--skip-hotwire |
略過 Hotwire 整合 |
--skip-jbuilder |
略過 jbuilder gem |
--skip-test |
略過測試檔案 |
--skip-system-test |
略過系統測試檔案 |
--skip-bootsnap |
略過 bootsnap gem |
--skip-dev-gems |
略過新增開發 gem |
這些只是 rails new
接受的部分選項。如需完整選項清單,請輸入 rails new --help
。
1.2 預先設定不同的資料庫
在建立新的 Rails 應用程式時,您可以指定應用程式要使用的資料庫類型。這將節省您幾分鐘的時間,當然也省下許多按鍵操作。
讓我們看看 --database=postgresql
選項會為我們做什麼
$ rails new petstore --database=postgresql
create
create app/controllers
create app/helpers
...
讓我們看看它在我們的 config/database.yml
中放了什麼
# PostgreSQL. Versions 9.3 and up are supported.
#
# Install the pg driver:
# gem install pg
# On macOS with Homebrew:
# gem install pg -- --with-pg-config=/usr/local/bin/pg_config
# On Windows:
# gem install pg
# Choose the win32 build.
# Install PostgreSQL and put its /bin directory on your path.
#
# Configure Using Gemfile
# gem "pg"
#
default: &default
adapter: postgresql
encoding: unicode
# For details on connection pooling, see Rails configuration guide
# https://rails-guides.dev.org.tw/configuring.html#database-pooling
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
development:
<<: *default
database: petstore_development
...
它產生了一個與我們選擇的 PostgreSQL 相應的資料庫設定。
2 命令列基礎
有幾個指令對您日常使用 Rails 絕對至關重要。按照您可能會使用它們的順序排列如下
bin/rails console
bin/rails server
bin/rails test
bin/rails generate
bin/rails db:migrate
bin/rails db:create
bin/rails routes
bin/rails dbconsole
rails new app_name
你可以輸入 rails --help
來取得目前可用的 rails 指令清單,這通常會根據你的目前目錄而有所不同。每個指令都有說明,應該可以幫助你找到你需要的事物。
$ rails --help
Usage:
bin/rails COMMAND [options]
You must specify a command. The most common commands are:
generate Generate new code (short-cut alias: "g")
console Start the Rails console (short-cut alias: "c")
server Start the Rails server (short-cut alias: "s")
...
All commands can be run with -h (or --help) for more information.
In addition to those commands, there are:
about List versions of all Rails ...
assets:clean[keep] Remove old compiled assets
assets:clobber Remove compiled assets
assets:environment Load asset compile environment
assets:precompile Compile all the assets ...
...
db:fixtures:load Load fixtures into the ...
db:migrate Migrate the database ...
db:migrate:status Display status of migrations
db:rollback Roll the schema back to ...
db:schema:cache:clear Clears a db/schema_cache.yml file
db:schema:cache:dump Create a db/schema_cache.yml file
db:schema:dump Create a database schema file (either db/schema.rb or db/structure.sql ...
db:schema:load Load a database schema file (either db/schema.rb or db/structure.sql ...
db:seed Load the seed data ...
db:version Retrieve the current schema ...
...
restart Restart app by touching ...
tmp:create Create tmp directories ...
2.1 bin/rails server
bin/rails server
指令會啟動一個名為 Puma 的網路伺服器,它與 Rails 捆綁在一起。每當你想要透過網路瀏覽器存取你的應用程式時,你都會使用這個指令。
bin/rails server
不需要進一步的作業,就會執行我們新的閃亮 Rails 應用程式
$ cd my_app
$ bin/rails server
=> Booting Puma
=> Rails 7.1.0 application starting in development
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Version 3.12.1 (ruby 2.5.7-p206), codename: Llamas in Pajamas
* Min threads: 5, max threads: 5
* Environment: development
* Listening on tcp://127.0.0.1:3000
Use Ctrl-C to stop
我們只用了三個指令就建立了一個 Rails 伺服器,監聽埠 3000。前往你的瀏覽器並開啟 https://127.0.0.1:3000,你會看到一個基本 Rails 應用程式正在執行。
你也可以使用別名「s」來啟動伺服器:bin/rails s
。
可以使用 -p
選項在不同的埠上執行伺服器。可以使用 -e
來變更預設的開發環境。
$ bin/rails server -e production -p 4000
-b
選項會將 Rails 繫結到指定的 IP,預設為 localhost。你可以透過傳遞 -d
選項來執行伺服器作為守護程式。
2.2 bin/rails generate
bin/rails generate
指令會使用範本來建立許多東西。單獨執行 bin/rails generate
會提供可用產生器的清單
你也可以使用別名「g」來呼叫產生器指令:bin/rails g
。
$ bin/rails generate
Usage:
bin/rails generate GENERATOR [args] [options]
...
...
Please choose a generator below.
Rails:
assets
channel
controller
generator
...
...
你可以透過產生器寶石安裝更多產生器,這些寶石是你無疑會安裝的附加元件的一部分,你甚至可以建立你自己的產生器!
使用產生器可以透過撰寫樣板程式碼,也就是應用程式運作所必需的程式碼,來節省大量時間。
讓我們使用控制器產生器建立自己的控制器。但我們應該使用什麼指令呢?我們來問產生器看看
所有 Rails 主控台工具都有說明文字。與大多數 *nix 工具一樣,您可以嘗試在結尾加上 --help
或 -h
,例如 bin/rails server --help
。
$ bin/rails generate controller
Usage:
bin/rails generate controller NAME [action action] [options]
...
...
Description:
...
To create a controller within a module, specify the controller name as a path like 'parent_module/controller_name'.
...
Example:
`bin/rails generate controller CreditCards open debit credit close`
Credit card controller with URLs like /credit_cards/debit.
Controller: app/controllers/credit_cards_controller.rb
Test: test/controllers/credit_cards_controller_test.rb
Views: app/views/credit_cards/debit.html.erb [...]
Helper: app/helpers/credit_cards_helper.rb
控制器產生器預期參數的格式為 generate controller ControllerName action1 action2
。讓我們建立一個 Greetings
控制器,並加上一個 hello 動作,它會對我們說些好聽的話。
$ bin/rails generate controller Greetings hello
create app/controllers/greetings_controller.rb
route get 'greetings/hello'
invoke erb
create app/views/greetings
create app/views/greetings/hello.html.erb
invoke test_unit
create test/controllers/greetings_controller_test.rb
invoke helper
create app/helpers/greetings_helper.rb
invoke test_unit
這產生了什麼?它確保我們的應用程式中有一堆目錄,並建立了一個控制器檔案、一個檢視檔案、一個功能測試檔案、一個檢視的輔助程式、一個 JavaScript 檔案和一個樣式表檔案。
查看控制器並稍加修改(在 app/controllers/greetings_controller.rb
中)
class GreetingsController < ApplicationController
def hello
@message = "Hello, how are you today?"
end
end
然後檢視,以顯示我們的訊息(在 app/views/greetings/hello.html.erb
中)
<h1>A Greeting for You!</h1>
<p><%= @message %></p>
使用 bin/rails server
啟動您的伺服器。
$ bin/rails server
=> Booting Puma...
網址會是 https://127.0.0.1:3000/greetings/hello。
在一般的純 Rails 應用程式中,您的網址通常會遵循 http://(主機)/(控制器)/(動作) 的模式,而類似 http://(主機)/(控制器) 的網址會呼叫該控制器的 index 動作。
Rails 也附帶一個資料模型產生器。
$ bin/rails generate model
Usage:
bin/rails generate model NAME [field[:type][:index] field[:type][:index]] [options]
...
ActiveRecord options:
[--migration], [--no-migration] # Indicates when to generate migration
# Default: true
...
Description:
Generates a new model. Pass the model name, either CamelCased or
under_scored, and an optional list of attribute pairs as arguments.
...
有關 type
參數可用的欄位類型清單,請參閱 API 文件 中 SchemaStatements
模組的 add_column 方法。index
參數會為欄位產生對應的索引。
但我們先不要直接產生模型(我們稍後會這麼做),而是先設定一個鷹架。Rails 中的鷹架是一組完整的模型、該模型的資料庫遷移、用來操作它的控制器、用來檢視和操作資料的檢視,以及上述每項的測試套件。
我們將設定一個稱為「HighScore」的簡單資源,用來追蹤我們在玩電子遊戲時獲得的最高分數。
$ bin/rails generate scaffold HighScore game:string score:integer
invoke active_record
create db/migrate/20190416145729_create_high_scores.rb
create app/models/high_score.rb
invoke test_unit
create test/models/high_score_test.rb
create test/fixtures/high_scores.yml
invoke resource_route
route resources :high_scores
invoke scaffold_controller
create app/controllers/high_scores_controller.rb
invoke erb
create app/views/high_scores
create app/views/high_scores/index.html.erb
create app/views/high_scores/edit.html.erb
create app/views/high_scores/show.html.erb
create app/views/high_scores/new.html.erb
create app/views/high_scores/_form.html.erb
invoke test_unit
create test/controllers/high_scores_controller_test.rb
create test/system/high_scores_test.rb
invoke helper
create app/helpers/high_scores_helper.rb
invoke test_unit
invoke jbuilder
create app/views/high_scores/index.json.jbuilder
create app/views/high_scores/show.json.jbuilder
create app/views/high_scores/_high_score.json.jbuilder
產生器會為 HighScore 建立模型、檢視、控制器、資源路由,以及資料庫遷移(會建立 high_scores
表)。而且會為這些項目新增測試。
遷移需要我們遷移,也就是執行一些 Ruby 程式碼(上述輸出的 20190416145729_create_high_scores.rb
檔案),以修改資料庫的架構。哪個資料庫?當我們執行 bin/rails db:migrate
指令時,Rails 會為你建立的 SQLite3 資料庫。我們稍後會詳細說明這個指令。
$ bin/rails db:migrate
== CreateHighScores: migrating ===============================================
-- create_table(:high_scores)
-> 0.0017s
== CreateHighScores: migrated (0.0019s) ======================================
讓我們來談談單元測試。單元測試就是測試程式碼並針對程式碼進行斷言的程式碼。在單元測試中,我們會取一小段程式碼,例如模型的方法,並測試其輸入和輸出。單元測試是你的好朋友。你愈早接受單元測試程式碼會大幅提升你的生活品質,愈好。真的。請參閱測試指南,深入了解單元測試。
讓我們看看 Rails 為我們建立的介面。
$ bin/rails server
開啟瀏覽器並開啟https://127.0.0.1:3000/high_scores,現在我們可以建立新的最高分數(太空侵略者 55,160 分!)
2.3 bin/rails console
console
指令讓你能夠從指令列與 Rails 應用程式互動。bin/rails console
在底層使用 IRB,因此如果你曾經使用過 IRB,你會覺得很熟悉。這對於使用程式碼測試快速構想,以及在不觸及網站的情況下變更資料伺服器端很有用。
你也可以使用別名「c」來呼叫主控台:bin/rails c
。
你可以指定 console
指令應在其中運作的環境。
$ bin/rails console -e staging
如果你想要測試一些程式碼而不變更任何資料,你可以透過呼叫 bin/rails console --sandbox
來執行。
$ bin/rails console --sandbox
Loading development environment in sandbox (Rails 7.1.0)
Any modifications you make will be rolled back on exit
irb(main):001:0>
2.3.1 app
和 helper
物件
在 bin/rails console
內部,你可以存取 app
和 helper
執行個體。
使用 app
方法,你可以存取命名路由輔助程式,以及執行要求。
irb> app.root_path
=> "/"
irb> app.get _
Started GET "/" for 127.0.0.1 at 2014-06-19 10:41:57 -0300
...
使用 helper
方法,你可以存取 Rails 和應用程式的輔助程式。
irb> helper.time_ago_in_words 30.days.ago
=> "about 1 month"
irb> helper.my_custom_helper
=> "my custom helper"
2.4 bin/rails dbconsole
bin/rails dbconsole
會找出你正在使用的資料庫,並把你帶入你會用來操作它的命令列介面(也會找出要給它的命令列參數!)。它支援 MySQL(包括 MariaDB)、PostgreSQL 和 SQLite3。
你也可以使用別名「db」來呼叫 dbconsole:bin/rails db
。
如果你正在使用多個資料庫,bin/rails dbconsole
預設會連線到主要資料庫。你可以使用 --database
或 --db
指定要連線的資料庫
$ bin/rails dbconsole --database=animals
2.5 bin/rails runner
runner
會在 Rails 的背景下非互動式地執行 Ruby 程式碼。例如
$ bin/rails runner "Model.long_running_method"
你也可以使用別名「r」來呼叫 runner:bin/rails r
。
你可以使用 -e
參數指定 runner
指令應該在什麼環境中執行。
$ bin/rails runner -e staging "Model.long_running_method"
你甚至可以使用 runner 執行寫在檔案中的 ruby 程式碼。
$ bin/rails runner lib/code_to_be_run.rb
2.6 bin/rails destroy
可以把 destroy
想成是 generate
的相反。它會找出 generate 做了什麼,然後撤銷它。
你也可以使用別名「d」來呼叫 destroy 指令:bin/rails d
。
$ bin/rails generate model Oops
invoke active_record
create db/migrate/20120528062523_create_oops.rb
create app/models/oops.rb
invoke test_unit
create test/models/oops_test.rb
create test/fixtures/oops.yml
$ bin/rails destroy model Oops
invoke active_record
remove db/migrate/20120528062523_create_oops.rb
remove app/models/oops.rb
invoke test_unit
remove test/models/oops_test.rb
remove test/fixtures/oops.yml
2.7 bin/rails about
bin/rails about
會提供有關 Ruby、RubyGems、Rails、Rails 子元件、你的應用程式資料夾、目前的 Rails 環境名稱、你的應用程式的資料庫轉接器和架構版本的資訊。當你需要尋求協助、檢查安全性修補程式是否會影響你,或是當你需要現有 Rails 安裝的某些統計資料時,這會很有用。
$ bin/rails about
About your application's environment
Rails version 7.1.0
Ruby version 2.7.0 (x86_64-linux)
RubyGems version 2.7.3
Rack version 2.0.4
JavaScript Runtime Node.js (V8)
Middleware: Rack::Sendfile, ActionDispatch::Static, ActionDispatch::Executor, ActiveSupport::Cache::Strategy::LocalCache::Middleware, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, ActionDispatch::RemoteIp, Sprockets::Rails::QuietAssets, Rails::Rack::Logger, ActionDispatch::ShowExceptions, WebConsole::Middleware, ActionDispatch::DebugExceptions, ActionDispatch::Reloader, ActionDispatch::Callbacks, ActiveRecord::Migration::CheckPending, ActionDispatch::Cookies, ActionDispatch::Session::CookieStore, ActionDispatch::Flash, Rack::Head, Rack::ConditionalGet, Rack::ETag
Application root /home/foobar/my_app
Environment development
Database adapter sqlite3
Database schema version 20180205173523
2.8 bin/rails assets:
你可以使用 bin/rails assets:precompile
預編譯 app/assets
中的資產,並使用 bin/rails assets:clean
移除較舊的編譯資產。assets:clean
指令允許滾動部署,在建置新資產時,仍可能連結到舊資產。
如果你想要完全清除 public/assets
,你可以使用 bin/rails assets:clobber
。
2.9 bin/rails db:
db:
rails 名稱空間中最常見的指令為 migrate
和 create
,而且嘗試所有 migration rails 指令(up
、down
、redo
、reset
)將會有回報。bin/rails db:version
在進行故障排除時很有用,它會告訴你資料庫的目前版本。
可以在 Migrations 指南中找到更多關於 migration 的資訊。
2.10 bin/rails notes
bin/rails notes
會在你的程式碼中搜尋以特定關鍵字開頭的註解。你可以參閱 bin/rails notes --help
以取得關於用法的資訊。
預設情況下,它會在 app
、config
、db
、lib
和 test
目錄中搜尋附檔名為 .builder
、.rb
、.rake
、.yml
、.yaml
、.ruby
、.css
、.js
和 .erb
的檔案中的 FIXME、OPTIMIZE 和 TODO 註解。
$ bin/rails notes
app/controllers/admin/users_controller.rb:
* [ 20] [TODO] any other way to do this?
* [132] [FIXME] high priority for next deploy
lib/school.rb:
* [ 13] [OPTIMIZE] refactor this code to make it faster
* [ 17] [FIXME]
2.10.1 註解
你可以使用 --annotations
參數傳遞特定註解。預設情況下,它會搜尋 FIXME、OPTIMIZE 和 TODO。請注意,註解區分大小寫。
$ bin/rails notes --annotations FIXME RELEASE
app/controllers/admin/users_controller.rb:
* [101] [RELEASE] We need to look at this before next release
* [132] [FIXME] high priority for next deploy
lib/school.rb:
* [ 17] [FIXME]
2.10.2 標籤
你可以使用 config.annotations.register_tags
新增更多預設標籤來搜尋。它會接收標籤清單。
config.annotations.register_tags("DEPRECATEME", "TESTME")
$ bin/rails notes
app/controllers/admin/users_controller.rb:
* [ 20] [TODO] do A/B testing on this
* [ 42] [TESTME] this needs more functional tests
* [132] [DEPRECATEME] ensure this method is deprecated in next release
2.10.3 目錄
你可以使用 config.annotations.register_directories
來新增更多預設目錄進行搜尋。它會接收一個目錄名稱清單。
config.annotations.register_directories("spec", "vendor")
$ bin/rails notes
app/controllers/admin/users_controller.rb:
* [ 20] [TODO] any other way to do this?
* [132] [FIXME] high priority for next deploy
lib/school.rb:
* [ 13] [OPTIMIZE] Refactor this code to make it faster
* [ 17] [FIXME]
spec/models/user_spec.rb:
* [122] [TODO] Verify the user that has a subscription works
vendor/tools.rb:
* [ 56] [TODO] Get rid of this dependency
2.10.4 擴充
你可以使用 config.annotations.register_extensions
來新增更多預設檔案副檔名進行搜尋。它會接收一個副檔名清單,並附上對應的正規表示式來進行比對。
config.annotations.register_extensions("scss", "sass") { |annotation| /\/\/\s*(#{annotation}):?\s*(.*)$/ }
$ bin/rails notes
app/controllers/admin/users_controller.rb:
* [ 20] [TODO] any other way to do this?
* [132] [FIXME] high priority for next deploy
app/assets/stylesheets/application.css.sass:
* [ 34] [TODO] Use pseudo element for this class
app/assets/stylesheets/application.css.scss:
* [ 1] [TODO] Split into multiple components
lib/school.rb:
* [ 13] [OPTIMIZE] Refactor this code to make it faster
* [ 17] [FIXME]
spec/models/user_spec.rb:
* [122] [TODO] Verify the user that has a subscription works
vendor/tools.rb:
* [ 56] [TODO] Get rid of this dependency
2.11 bin/rails routes
bin/rails routes
會列出所有你定義好的路由,這對於追蹤應用程式中的路由問題很有用,或者可以讓你快速了解你正在嘗試熟悉的應用程式中的 URL。
2.12 bin/rails test
可以在 Rails 應用程式測試指南 中找到 Rails 單元測試的詳細說明。
Rails 內建一個名為 minitest 的測試架構。Rails 的穩定性歸功於測試的使用。test:
名稱空間中可用的指令有助於執行你希望撰寫的不同測試。
2.13 bin/rails tmp:
Rails.root/tmp
目錄就像 *nix /tmp 目錄一樣,是暫存檔案的存放位置,例如處理序 ID 檔案和快取動作。
tmp:
名稱空間的指令將有助於你清除和建立 Rails.root/tmp
目錄。
bin/rails tmp:cache:clear
會清除tmp/cache
。bin/rails tmp:sockets:clear
會清除tmp/sockets
。bin/rails tmp:screenshots:clear
會清除tmp/screenshots
。bin/rails tmp:clear
會清除所有快取、socket 和螢幕擷取檔案。bin/rails tmp:create
會建立快取、socket 和 PID 的 tmp 目錄。
2.14 其他
bin/rails initializers
會印出所有已定義的初始化程式,順序為 Rails 呼叫它們的順序。bin/rails middleware
會列出應用程式啟用的 Rack 中介軟體堆疊。bin/rails stats
非常適合查看程式碼的統計資料,例如顯示 KLOC(數千行程式碼)和程式碼對測試的比例。bin/rails secret
會提供一個偽亂數金鑰,可供您用於會話金鑰。bin/rails time:zones:all
會列出 Rails 知道的所有時區。
2.15 自訂 Rake 任務
自訂 rake 任務有 .rake
副檔名,並置於 Rails.root/lib/tasks
。您可以使用 bin/rails generate task
指令建立這些自訂 rake 任務。
desc "I am short, but comprehensive description for my cool task"
task task_name: [:prerequisite_task, :another_task_we_depend_on] do
# All your magic here
# Any valid Ruby code is allowed
end
傳遞引數給自訂 rake 任務
task :task_name, [:arg_1] => [:prerequisite_1, :prerequisite_2] do |task, args|
argument_1 = args.arg_1
end
您可以透過將任務置於命名空間中來分組任務
namespace :db do
desc "This task does nothing"
task :nothing do
# Seriously, nothing
end
end
呼叫任務的方式如下
$ bin/rails task_name
$ bin/rails "task_name[value 1]" # entire argument string should be quoted
$ bin/rails "task_name[value 1,value2,value3]" # separate multiple args with a comma
$ bin/rails db:nothing
如果您需要與應用程式模型互動、執行資料庫查詢等,您的任務應依賴於 environment
任務,它會載入您的應用程式程式碼。
task task_that_requires_app_code: [:environment] do
User.create!
end
回饋
我們鼓勵您協助改善本指南的品質。
如果您發現任何錯字或事實錯誤,請貢獻您的心力。首先,您可以閱讀我們的 文件貢獻 部分。
您也可能發現不完整或過時的內容。請為 main 新增任何遺漏的文件。請務必先查看 Edge Guides,以驗證問題是否已在 main 分支中修正。查看 Ruby on Rails 指南指南 以了解風格和慣例。
如果您發現需要修正的地方,但無法自行修補,請 開啟問題。
最後,我們非常歡迎在 官方 Ruby on Rails 論壇 上進行任何有關 Ruby on Rails 文件的討論。