# Rails 命令行 讀完本文，你將學到： * 如何新建 Rails 程序； * 如何生成模型、控制器、數據庫遷移和單元測試； * 如何啟動開發服務器； * 如果在交互 shell 中測試對象； * 如何分析、評測程序； ### Chapters 1. [命令行基礎](#%E5%91%BD%E4%BB%A4%E8%A1%8C%E5%9F%BA%E7%A1%80) * [`rails new`](#rails-new) * [`rails server`](#rails-server) * [`rails generate`](#rails-generate) * [`rails console`](#rails-console) * [`rails dbconsole`](#rails-dbconsole) * [`rails runner`](#rails-runner) * [`rails destroy`](#rails-destroy) 2. [Rake](#rake) * [`about`](#about) * [`assets`](#assets) * [`db`](#db) * [`doc`](#doc) * [`notes`](#notes) * [`routes`](#routes) * [`test`](#test) * [`tmp`](#tmp) * [其他任務](#%E5%85%B6%E4%BB%96%E4%BB%BB%E5%8A%A1) * [編寫 Rake 任務](#%E7%BC%96%E5%86%99-rake-%E4%BB%BB%E5%8A%A1) 3. [Rails 命令行高級用法](#rails-%E5%91%BD%E4%BB%A4%E8%A1%8C%E9%AB%98%E7%BA%A7%E7%94%A8%E6%B3%95) * [新建程序時指定數據庫和源碼管理系統](#%E6%96%B0%E5%BB%BA%E7%A8%8B%E5%BA%8F%E6%97%B6%E6%8C%87%E5%AE%9A%E6%95%B0%E6%8D%AE%E5%BA%93%E5%92%8C%E6%BA%90%E7%A0%81%E7%AE%A1%E7%90%86%E7%B3%BB%E7%BB%9F) 閱讀本文前要具備一些 Rails 基礎知識，可以閱讀“[Rails 入門](getting_started.html)”一文。 ### 1 命令行基礎 有些命令在 Rails 開發過程中經常會用到，下面按照使用頻率倒序列出： * `rails console` * `rails server` * `rake` * `rails generate` * `rails dbconsole` * `rails new app_name` 這些命令都可指定 `-h` 或 `--help` 選項顯示具體用法。 下面我們來新建一個 Rails 程序，介紹各命令的用法。 #### 1.1 `rails new` 安裝 Rails 后首先要做的就是使用 `rails new` 命令新建 Rails 程序。 如果還沒安裝 Rails ，可以執行 `gem install rails` 命令安裝。 ``` $ rails new commandsapp create create README.rdoc create Rakefile create config.ru create .gitignore create Gemfile create app ... create tmp/cache ... run bundle install ``` 這個簡單的命令會生成很多文件，組成一個完整的 Rails 程序，直接就可運行。 #### 1.2 `rails server` `rails server` 命令會啟動 Ruby 內建的小型服務器 WEBrick。要想在瀏覽器中訪問程序，就要執行這個命令。 無需其他操作，執行 `rails server` 命令后就能運行剛創建的 Rails 程序： ``` $ cd commandsapp $ rails server => Booting WEBrick => Rails 4.2.0 application starting in development on http://0.0.0.0:3000 => Call with -d to detach => Ctrl-C to shutdown server [2013-08-07 02:00:01] INFO WEBrick 1.3.1 [2013-08-07 02:00:01] INFO ruby 2.0.0 (2013-06-27) [x86_64-darwin11.2.0] [2013-08-07 02:00:01] INFO WEBrick::HTTPServer#start: pid=69680 port=3000 ``` 只執行了三個命令，我們就啟動了一個 Rails 服務器，監聽端口 3000。打開瀏覽器，訪問 [http://localhost:3000](http://localhost:3000)，會看到一個簡單的 Rails 程序。 啟動服務器的命令還可使用別名“s”：`rails s`。 如果想讓服務器監聽其他端口，可通過 `-p` 選項指定。所處的環境可由 `-e` 選項指定。 ``` $ rails server -e production -p 4000 ``` `-b` 選項把 Rails 綁定到指定的 IP，默認 IP 是 0.0.0.0。指定 `-d` 選項后，服務器會以守護進程的形式運行。 #### 1.3 `rails generate` `rails generate` 使用模板生成很多東西。單獨執行 `rails generate` 命令，會列出可用的生成器： 還可使用別名“g”執行生成器命令：`rails g`。 ``` $ rails generate Usage: rails generate GENERATOR [args] [options] ... ... Please choose a generator below. Rails: assets controller generator ... ... ``` 使用其他生成器 gem 可以安裝更多的生成器，或者使用插件中提供的生成器，甚至還可以自己編寫生成器。 使用生成器可以節省大量編寫程序骨架的時間。 下面我們使用控制器生成器生成控制器。但應該使用哪個命令呢？我們問一下生成器： 所有的 Rails 命令都有幫助信息。和其他 *nix 命令一樣，可以在命令后加上 `--help` 或 `-h` 選項，例如 `rails server --help`。 ``` $ rails generate controller Usage: 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: `rails generate controller CreditCard open debit credit close` Credit card controller with URLs like /credit_card/debit. Controller: app/controllers/credit_card_controller.rb Test: test/controllers/credit_card_controller_test.rb Views: app/views/credit_card/debit.html.erb [...] Helper: app/helpers/credit_card_helper.rb ``` 控制器生成器接受的參數形式是 `generate controller ControllerName action1 action2`。下面我們來生成 `Greetings` 控制器，包含一個動作 `hello`，跟讀者打個招呼。 ``` $ 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 create test/helpers/greetings_helper_test.rb invoke assets invoke coffee create app/assets/javascripts/greetings.js.coffee invoke scss create app/assets/stylesheets/greetings.css.scss ``` 這個命令生成了什么呢？在程序中創建了一堆文件夾，還有控制器文件、視圖文件、功能測試文件、視圖幫助方法文件、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> ``` 執行 `rails server` 命令啟動服務器： ``` $ rails server => Booting WEBrick... ``` 要查看的地址是 [http://localhost:3000/greetings/hello](http://localhost:3000/greetings/hello)。 在常規的 Rails 程序中，URL 的格式是 http://(host)/(controller)/(action)，訪問 http://(host)/(controller) 會進入控制器的 `index` 動作。 Rails 也為數據模型提供了生成器。 ``` $ rails generate model Usage: rails generate model NAME [field[:type][:index] field[:type][:index]] [options] ... Active Record options: [--migration] # Indicates when to generate migration # Default: true ... Description: Create rails files for model generator. ``` 全部可用的字段類型，請查看 `TableDefinition#column` 方法的[文檔](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html#method-i-column)。 不過我們暫且不單獨生成模型（后文再生成），先使用腳手架。Rails 中的腳手架會生成資源所需的全部文件，包括：模型，模型所用的遷移，處理模型的控制器，查看數據的視圖，以及測試組件。 我們要創建一個名為“HighScore”的資源，記錄視頻游戲的最高得分。 ``` $ rails generate scaffold HighScore game:string score:integer invoke active_record create db/migrate/20130717151933_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 invoke helper create app/helpers/high_scores_helper.rb invoke test_unit create test/helpers/high_scores_helper_test.rb invoke jbuilder create app/views/high_scores/index.json.jbuilder create app/views/high_scores/show.json.jbuilder invoke assets invoke coffee create app/assets/javascripts/high_scores.js.coffee invoke scss create app/assets/stylesheets/high_scores.css.scss invoke scss identical app/assets/stylesheets/scaffolds.css.scss ``` 這個生成器檢測到以下各組件對應的文件夾已經存儲在：模型，控制器，幫助方法，布局，功能測試，單元測試，樣式表。然后創建“HighScore”資源的視圖、控制器、模型和遷移文件（用來創建 `high_scores` 數據表和字段），并設置好路由，以及測試等。 我們要運行遷移，執行文件 `20130717151933_create_high_scores.rb` 中的代碼，這才能修改數據庫的模式。那么要修改哪個數據庫呢？執行 `rake db:migrate` 命令后會生成 SQLite3 數據庫。稍后再詳細介紹 Rake。 ``` $ rake db:migrate == CreateHighScores: migrating =============================================== -- create_table(:high_scores) -> 0.0017s == CreateHighScores: migrated (0.0019s) ====================================== ``` 介紹一下單元測試。單元測試是用來測試代碼、做斷定的代碼。在單元測試中，我們只關注代碼的一部分，例如模型中的一個方法，測試其輸入和輸出。單元測試是你的好伙伴，你逐漸會意識到，單元測試的程度越高，生活的質量才能提上來。真的。稍后我們會編寫一個單元測試。 我們來看一下 Rails 創建的界面。 ``` $ rails server ``` 打開瀏覽器，訪問 [http://localhost:3000/high_scores](http://localhost:3000/high_scores)，現在可以創建新的最高得分了（太空入侵者得了 55,160 分）。 #### 1.4 `rails console` 執行 `console` 命令后，可以在命令行中和 Rails 程序交互。`rails` console` 使用的是 IRB，所以如果你用過 IRB 的話，操作起來很順手。在終端里可以快速測試想法，或者修改服務器端的數據，而無需在網站中操作。 這個命令還可以使用別名“c”：`rails c`。 執行 `console` 命令時可以指定終端在哪個環境中打開： ``` $ rails console staging ``` 如果你想測試一些代碼，但不想改變存儲的數據，可以執行 `rails console --sandbox`。 ``` $ rails console --sandbox Loading development environment in sandbox (Rails 4.2.0) Any modifications you make will be rolled back on exit irb(main):001:0> ``` #### 1.5 `rails dbconsole` `rails dbconsole` 能檢測到你正在使用的數據庫類型（還能理解傳入的命令行參數），然后進入該數據庫的命令行界面。該命令支持 MySQL，PostgreSQL，SQLite 和 SQLite3。 這個命令還可使用別名“db”：`rails db`。 #### 1.6 `rails runner` `runner` 可以以非交互的方式在 Rails 中運行 Ruby 代碼。例如： ``` $ rails runner "Model.long_running_method" ``` 這個命令還可使用別名“r”：`rails r`。 可使用 `-e` 選項指定 `runner` 命令在哪個環境中運行。 ``` $ rails runner -e staging "Model.long_running_method" ``` #### 1.7 `rails destroy` `destroy` 可以理解成 `generate` 的逆操作，能識別生成了什么，然后將其刪除。 這個命令還可使用別名“d”：`rails d`。 ``` $ 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 ``` ``` $ 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 Rake Rake 是 Ruby 領域的 Make，是個獨立的 Ruby 工具，目的是代替 Unix 中的 make。Rake 根據 `Rakefile` 和 `.rake` 文件構建任務。Rails 使用 Rake 實現常見的管理任務，尤其是較為復雜的任務。 執行 `rake -- tasks` 命令可以列出所有可用的 Rake 任務，具體的任務根據所在文件夾會有所不同。每個任務都有描述信息，幫助你找到所需的命令。 要想查看執行 Rake 任務時的完整調用棧，可以在命令中使用 `--trace` 選項，例如 `rake db:create --trace`。 ``` $ rake --tasks rake about # List versions of all Rails frameworks and the environment rake assets:clean # Remove compiled assets rake assets:precompile # Compile all the assets named in config.assets.precompile rake db:create # Create the database from config/database.yml for the current Rails.env ... rake log:clear # Truncates all *.log files in log/ to zero bytes (specify which logs with LOGS=test,development) rake middleware # Prints out your Rack middleware stack ... rake tmp:clear # Clear session, cache, and socket files from tmp/ (narrow w/ tmp:sessions:clear, tmp:cache:clear, tmp:sockets:clear) rake tmp:create # Creates tmp directories for sessions, cache, sockets, and pids ``` 還可以執行 `rake -T` 查看所有任務。 #### 2.1 `about` `rake about` 任務輸出以下信息：Ruby、RubyGems、Rails 的版本號，Rails 使用的組件，程序所在的文件夾，Rails 當前所處的環境名，程序使用的數據庫適配器，數據庫模式版本號。如果想向他人需求幫助，檢查安全補丁是否影響程序，或者需要查看現有 Rails 程序的信息，可以使用這個任務。 ``` $ rake about About your application's environment Ruby version 1.9.3 (x86_64-linux) RubyGems version 1.3.6 Rack version 1.3 Rails version 4.2.0 JavaScript Runtime Node.js (V8) Active Record version 4.2.0 Action Pack version 4.2.0 Action View version 4.2.0 Action Mailer version 4.2.0 Active Support version 4.2.0 Middleware Rack::Sendfile, ActionDispatch::Static, Rack::Lock, #<ActiveSupport::Cache::Strategy::LocalCache::Middleware:0x007ffd131a7c88>, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, Rails::Rack::Logger, ActionDispatch::ShowExceptions, ActionDispatch::DebugExceptions, ActionDispatch::RemoteIp, ActionDispatch::Reloader, ActionDispatch::Callbacks, ActiveRecord::Migration::CheckPending, ActiveRecord::ConnectionAdapters::ConnectionManagement, ActiveRecord::QueryCache, ActionDispatch::Cookies, ActionDispatch::Session::CookieStore, ActionDispatch::Flash, ActionDispatch::ParamsParser, Rack::Head, Rack::ConditionalGet, Rack::ETag Application root /home/foobar/commandsapp Environment development Database adapter sqlite3 Database schema version 20110805173523 ``` #### 2.2 `assets` `rake assets:precompile` 任務會預編譯 `app/assets` 文件夾中的靜態資源文件。`rake assets:clean` 任務會把編譯好的靜態資源文件刪除。 #### 2.3 `db` Rake 命名空間 `db:` 中最常用的任務是 `migrate` 和 `create`，這兩個任務會嘗試運行所有遷移相關的 Rake 任務（`up`，`down`，`redo`，`reset`）。`rake db:version` 在排查問題時很有用，會輸出數據庫的當前版本。 關于數據庫遷移的更多介紹，參閱“[Active Record 數據庫遷移](migrations.html)”一文。 #### 2.4 `doc` `doc:` 命名空間中的任務可以生成程序的文檔，Rails API 文檔和 Rails 指南。生成的文檔可以隨意分割，減少程序的大小，適合在嵌入式平臺使用。 * `rake doc:app` 在 `doc/app` 文件夾中生成程序的文檔； * `rake doc:guides` 在 `doc/guides` 文件夾中生成 Rails 指南； * `rake doc:rails` 在 `doc/api` 文件夾中生成 Rails API 文檔； #### 2.5 `notes` `rake notes` 會搜索整個程序，尋找以 FIXME、OPTIMIZE 或 TODO 開頭的注釋。搜索的文件包括 `.builder`，`.rb`，`.erb`，`.haml`，`.slim`，`.css`，`.scss`，`.js`，`.coffee`，`.rake`，`.sass` 和 `.less`。搜索的內容包括默認注解和自定義注解。 ``` $ rake notes (in /home/foobar/commandsapp) app/controllers/admin/users_controller.rb: * [ 20] [TODO] any other way to do this? * [132] [FIXME] high priority for next deploy app/models/school.rb: * [ 13] [OPTIMIZE] refactor this code to make it faster * [ 17] [FIXME] ``` 如果想查找特定的注解，例如 FIXME，可以執行 `rake notes:fixme` 任務。注意，在命令中注解的名字要使用小寫形式。 ``` $ rake notes:fixme (in /home/foobar/commandsapp) app/controllers/admin/users_controller.rb: * [132] high priority for next deploy app/models/school.rb: * [ 17] ``` 在代碼中可以使用自定義的注解，然后執行 `rake notes:custom` 任務，并使用 `ANNOTATION` 環境變量指定要查找的注解。 ``` $ rake notes:custom ANNOTATION=BUG (in /home/foobar/commandsapp) app/models/post.rb: * [ 23] Have to fix this one before pushing! ``` 注意，不管查找的是默認的注解還是自定義的直接，注解名（例如 FIXME，BUG 等）不會在輸出結果中顯示。 默認情況下，`rake notes` 會搜索 `app`、`config`、`lib`、`bin` 和 `test` 這幾個文件夾中的文件。如果想在其他的文件夾中查找，可以使用 `SOURCE_ANNOTATION_DIRECTORIES` 環境變量指定一個以逗號分隔的列表。 ``` $ export SOURCE_ANNOTATION_DIRECTORIES='spec,vendor' $ rake notes (in /home/foobar/commandsapp) app/models/user.rb: * [ 35] [FIXME] User should have a subscription at this point spec/models/user_spec.rb: * [122] [TODO] Verify the user that has a subscription works ``` #### 2.6 `routes` `rake routes` 會列出程序中定義的所有路由，可為解決路由問題提供幫助，還可以讓你對程序中的所有 URL 有個整體了解。 #### 2.7 `test` Rails 中的單元測試詳情，參見“[Rails 程序測試指南](testing.html)”一文。 Rails 提供了一個名為 Minitest 的測試組件。Rails 的穩定性也由測試決定。`test:` 命名空間中的任務可用于運行各種測試。 #### 2.8 `tmp` `Rails.root/tmp` 文件夾和 *nix 中的 `/tmp` 作用相同，用來存放臨時文件，例如會話（如果使用文件存儲會話）、PID 文件和緩存文件等。 `tmp:` 命名空間中的任務可以清理或創建 `Rails.root/tmp` 文件夾： * `rake tmp:cache:clear` 清理 `tmp/cache` 文件夾； * `rake tmp:sessions:clear` 清理 `tmp/sessions` 文件夾； * `rake tmp:sockets:clear` 清理 `tmp/sockets` 文件夾； * `rake tmp:clear` 清理以上三個文件夾； * `rake tmp:create` 創建會話、緩存、套接字和 PID 所需的臨時文件夾； #### 2.9 其他任務 * `rake stats` 用來統計代碼狀況，顯示千行代碼數和測試比例等； * `rake secret` 會生成一個偽隨機字符串，作為會話的密鑰； * `rake time:zones:all` 列出 Rails 能理解的所有時區； #### 2.10 編寫 Rake 任務 自己編寫的 Rake 任務保存在 `Rails.root/lib/tasks` 文件夾中，文件的擴展名是 `.rake`。執行 `bin/rails generate task` 命令會生成一個新的自定義任務文件。 ``` 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 ``` 向自定義的任務中傳入參數的方式如下： ``` task :task_name, [:arg_1] => [:pre_1, :pre_2] do |t, args| # You can use args from here end ``` 任務可以分組，放入命名空間： ``` namespace :db do desc "This task does nothing" task :nothing do # Seriously, nothing end end ``` 執行任務的方法如下： ``` rake task_name rake "task_name[value 1]" # entire argument string should be quoted rake db:nothing ``` 如果在任務中要和程序的模型交互，例如查詢數據庫等，可以使用 `environment` 任務，加載程序代碼。 ### 3 Rails 命令行高級用法 Rails 命令行的高級用法就是找到實用的參數，滿足特定需求或者工作流程。下面是一些常用的高級命令。 #### 3.1 新建程序時指定數據庫和源碼管理系統 新建程序時，可設置一些選項指定使用哪種數據庫和源碼管理系統。這么做可以節省一點時間，減少敲擊鍵盤的次數。 我們來看一下 `--git` 和 `--database=postgresql` 選項有什么作用： ``` $ mkdir gitapp $ cd gitapp $ git init Initialized empty Git repository in .git/ $ rails new . --git --database=postgresql exists create app/controllers create app/helpers ... ... create tmp/cache create tmp/pids create Rakefile add 'Rakefile' create README.rdoc add 'README.rdoc' create app/controllers/application_controller.rb add 'app/controllers/application_controller.rb' create app/helpers/application_helper.rb ... create log/test.log add 'log/test.log' ``` 上面的命令先新建一個 `gitapp` 文件夾，初始化一個空的 git 倉庫，然后再把 Rails 生成的文件加入倉庫。再來看一下在數據庫設置文件中添加了什么： ``` $ cat config/database.yml # PostgreSQL. Versions 8.2 and up are supported. # # Install the pg driver: # gem install pg # On OS X with Homebrew: # gem install pg -- --with-pg-config=/usr/local/bin/pg_config # On OS X with MacPorts: # gem install pg -- --with-pg-config=/opt/local/lib/postgresql84/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' # development: adapter: postgresql encoding: unicode database: gitapp_development pool: 5 username: gitapp password: ... ... ``` 這個命令還根據我們選擇的 PostgreSQL 數據庫在 `database.yml` 中添加了一些設置。 指定源碼管理系統選項時唯一的不便是，要先新建程序的文件夾，再初始化源碼管理系統，然后才能執行 `rails new` 命令生成程序骨架。 ### 反饋 歡迎幫忙改善指南質量。 如發現任何錯誤，歡迎修正。開始貢獻前，可先行閱讀[貢獻指南：文檔](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)。