v7.1.3.2
更多資訊請至 rubyonrails.org: 更多 Ruby on Rails

Rails 指令列

閱讀本指南後,你將知道

本教學假設你已具備閱讀 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 apphelper 物件

bin/rails console 內部,你可以存取 apphelper 執行個體。

使用 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 名稱空間中最常見的指令為 migratecreate,而且嘗試所有 migration rails 指令(updownredoreset)將會有回報。bin/rails db:version 在進行故障排除時很有用,它會告訴你資料庫的目前版本。

可以在 Migrations 指南中找到更多關於 migration 的資訊。

2.10 bin/rails notes

bin/rails notes 會在你的程式碼中搜尋以特定關鍵字開頭的註解。你可以參閱 bin/rails notes --help 以取得關於用法的資訊。

預設情況下,它會在 appconfigdblibtest 目錄中搜尋附檔名為 .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 文件的討論。