Active Model 基礎

本指南將提供您開始使用 Active Model 所需的知識。Active Model 提供一種讓 Action Pack 和 Action View 輔助方法與普通 Ruby 物件互動的方式。它還有助於建立自訂 ORM，以便在 Rails 框架之外使用。

閱讀本指南後，您將了解

Active Model 是什麼，以及它與 Active Record 的關係。
Active Model 中包含的不同模組。
如何在您的類別中使用 Active Model。

1 什麼是 Active Model？

要了解 Active Model，您需要稍微了解 Active Record。Active Record 是一個 ORM（物件關聯對映器），它將需要永久儲存的資料的物件連接到關聯式資料庫。但是，它具有在 ORM 之外有用的功能，其中一些包括驗證、回呼、翻譯、建立自訂屬性的能力等等。

其中一些功能已從 Active Record 中抽象出來，形成 Active Model。Active Model 是一個包含各種模組的函式庫，這些模組可用於需要類似模型的功能，但不與資料庫中的任何表格綁定的普通 Ruby 物件。

總而言之，雖然 Active Record 提供一個介面來定義對應於資料庫表格的模型，但 Active Model 提供功能來建立不一定需要資料庫支援的類似模型的 Ruby 類別。Active Model 可以獨立於 Active Record 使用。

以下說明其中一些模組。

1.1 API

ActiveModel::API 讓類別能夠直接與 Action Pack 和 Action View 搭配使用。

當包含 ActiveModel::API 時，預設會包含其他模組，讓您可以使用以下功能

屬性賦值
轉換
命名
翻譯
驗證

以下是一個包含 ActiveModel::API 的類別範例，以及如何使用它

class EmailContact
  include ActiveModel::API

  attr_accessor :name, :email, :message
  validates :name, :email, :message, presence: true

  def deliver
    if valid?
      # Deliver email
    end
  end
end

irb> email_contact = EmailContact.new(name: "David", email: "david@example.com", message: "Hello World")

irb> email_contact.name # Attribute Assignment
=> "David"

irb> email_contact.to_model == email_contact # Conversion
=> true

irb> email_contact.model_name.name # Naming
=> "EmailContact"

irb> EmailContact.human_attribute_name("name") # Translation if the locale is set
=> "Name"

irb> email_contact.valid? # Validations
=> true

irb> empty_contact = EmailContact.new
irb> empty_contact.valid?
=> false

任何包含 ActiveModel::API 的類別都可以與 form_with、render 和任何其他 Action View 輔助方法一起使用，就像 Active Record 物件一樣。

例如，form_with 可以用來為 EmailContact 物件建立表單，如下所示

<%= form_with model: EmailContact.new do |form| %>
  <%= form.text_field :name %>
<% end %>

這會產生以下 HTML

<form action="/email_contacts" method="post">
  <input type="text" name="email_contact[name]" id="email_contact_name">
</form>

render 可以用來使用物件渲染局部範本

<%= render @email_contact %>

您可以在 Action View 表單輔助方法和佈局和渲染指南中，分別了解如何將 form_with 和 render 與相容於 ActiveModel::API 的物件搭配使用。

1.2 模型

ActiveModel::Model 預設包含 ActiveModel::API，以便與 Action Pack 和 Action View 互動，而且是實作類似模型之 Ruby 類別的建議方法。它將在未來擴充以新增更多功能。

class Person
  include ActiveModel::Model

  attr_accessor :name, :age
end

irb> person = Person.new(name: 'bob', age: '18')
irb> person.name # => "bob"
irb> person.age  # => "18"

1.3 屬性

ActiveModel::Attributes 可讓您在普通的 Ruby 物件上定義資料類型、設定預設值，以及處理轉換和序列化。這對於表單資料很有用，它將針對一般物件產生類似 Active Record 的日期和布林值轉換。

要使用 Attributes，請將模組包含在您的模型類別中，並使用 attribute 巨集來定義您的屬性。它接受一個名稱、一個轉換類型、一個預設值，以及屬性類型支援的任何其他選項。

class Person
  include ActiveModel::Attributes

  attribute :name, :string
  attribute :date_of_birth, :date
  attribute :active, :boolean, default: true
end

irb> person = Person.new

irb> person.name = "Jane"
irb> person.name
=> "Jane"

# Casts the string to a date set by the attribute
irb> person.date_of_birth = "2020-01-01"
irb> person.date_of_birth
=> Wed, 01 Jan 2020
irb> person.date_of_birth.class
=> Date

# Uses the default value set by the attribute
irb> person.active
=> true

# Casts the integer to a boolean set by the attribute
irb> person.active = 0
irb> person.active
=> false

使用 ActiveModel::Attributes 時，可以使用以下說明的其他方法。

1.3.1 方法：`attribute_names`

attribute_names 方法會傳回屬性名稱的陣列。

irb> Person.attribute_names
=> ["name", "date_of_birth", "active"]

1.3.2 方法：`attributes`

attributes 方法會傳回所有屬性的雜湊，其中屬性名稱為鍵，屬性的值為值。

irb> person.attributes
=> {"name" => "Jane", "date_of_birth" => Wed, 01 Jan 2020, "active" => false}

1.4 屬性賦值

ActiveModel::AttributeAssignment 可讓您透過傳入屬性雜湊 (其鍵與屬性名稱相符) 來設定物件的屬性。當您想要一次設定多個屬性時，這非常有用。

考量以下類別

class Person
  include ActiveModel::AttributeAssignment

  attr_accessor :name, :date_of_birth, :active
end

irb> person = Person.new

# Set multiple attributes at once
irb> person.assign_attributes(name: "John", date_of_birth: "1998-01-01", active: false)

irb> person.name
=> "John"
irb> person.date_of_birth
=> Thu, 01 Jan 1998
irb> person.active
=> false

如果傳入的雜湊回應 permitted? 方法，而且此方法的傳回值為 false，則會引發 ActiveModel::ForbiddenAttributesError 例外狀況。

permitted? 用於強參數整合，您藉此從請求中指派參數屬性。

irb> person = Person.new

# Using strong parameters checks, build a hash of attributes similar to params from a request
irb> params = ActionController::Parameters.new(name: "John")
=> #<ActionController::Parameters {"name" => "John"} permitted: false>

irb> person.assign_attributes(params)
=> # Raises ActiveModel::ForbiddenAttributesError
irb> person.name
=> nil

# Permit the attributes we want to allow assignment
irb> permitted_params = params.permit(:name)
=> #<ActionController::Parameters {"name" => "John"} permitted: true>

irb> person.assign_attributes(permitted_params)
irb> person.name
=> "John"

1.4.1 方法別名：`attributes=`

assign_attributes 方法有一個別名 attributes=。

方法別名是一個執行與另一個方法相同動作的方法，但其呼叫方式不同。別名的存在是為了方便讀取和方便性。

以下範例示範如何使用 attributes= 方法一次設定多個屬性

irb> person = Person.new

irb> person.attributes = { name: "John", date_of_birth: "1998-01-01", active: false }

irb> person.name
=> "John"
irb> person.date_of_birth
=> "1998-01-01"

assign_attributes 和 attributes= 都是方法呼叫，並接受要指派的屬性雜湊作為引數。在許多情況下，Ruby 允許從方法呼叫中省略括號 ()，並從雜湊定義中省略大括號 {}。

「設定器」方法 (例如 attributes=) 通常不含 () 撰寫，即使包含它們的作用相同，而且它們需要雜湊永遠包含 {}。person.attributes=({ name: "John" }) 可以接受，但 person.attributes = name: "John" 會產生 SyntaxError。

其他方法呼叫 (例如 assign_attributes) 的雜湊引數可能包含或不包含括號 () 和 {}。例如，assign_attributes name: "John" 和 assign_attributes({ name: "John" }) 都是完全有效的 Ruby 程式碼，但是 assign_attributes { name: "John" } 無效，因為 Ruby 無法區分該雜湊引數與區塊，而且會引發 SyntaxError。

1.5 屬性方法

ActiveModel::AttributeMethods 提供了一種為模型的屬性動態定義方法的方式。這個模組特別適用於簡化屬性的存取和操作，並且可以為類別的方法添加自訂的前綴和後綴。您可以定義前綴和後綴，以及物件上的哪些方法會使用它們，如下所示：

在您的類別中引入 ActiveModel::AttributeMethods。
呼叫您想要添加的每個方法，例如 attribute_method_suffix、attribute_method_prefix、attribute_method_affix。
在其他方法之後呼叫 define_attribute_methods，以宣告應該加上前綴和後綴的屬性。
定義您已宣告的各種通用 _attribute 方法。這些方法中的參數 attribute 將會被傳遞到 define_attribute_methods 中的參數取代。在下面的範例中，它是 name。

attribute_method_prefix 和 attribute_method_suffix 用於定義將用於建立方法的前綴和後綴。attribute_method_affix 用於同時定義前綴和後綴。

class Person
  include ActiveModel::AttributeMethods

  attribute_method_affix prefix: "reset_", suffix: "_to_default!"
  attribute_method_prefix "first_", "last_"
  attribute_method_suffix "_short?"

  define_attribute_methods "name"

  attr_accessor :name

  private
    # Attribute method call for 'first_name'
    def first_attribute(attribute)
      public_send(attribute).split.first
    end

    # Attribute method call for 'last_name'
    def last_attribute(attribute)
      public_send(attribute).split.last
    end

    # Attribute method call for 'name_short?'
    def attribute_short?(attribute)
      public_send(attribute).length < 5
    end

    # Attribute method call 'reset_name_to_default!'
    def reset_attribute_to_default!(attribute)
      public_send("#{attribute}=", "Default Name")
    end
end

irb> person = Person.new
irb> person.name = "Jane Doe"

irb> person.first_name
=> "Jane"
irb> person.last_name
=> "Doe"

irb> person.name_short?
=> false

irb> person.reset_name_to_default!
=> "Default Name"

如果您呼叫未定義的方法，它將引發 NoMethodError 錯誤。

1.5.1 方法：`alias_attribute`

ActiveModel::AttributeMethods 使用 alias_attribute 提供屬性方法的別名。

下面的範例為名為 full_name 的 name 建立別名屬性。它們返回相同的值，但別名 full_name 更能反映該屬性包含名字和姓氏。

class Person
  include ActiveModel::AttributeMethods

  attribute_method_suffix "_short?"
  define_attribute_methods :name

  attr_accessor :name

  alias_attribute :full_name, :name

  private
    def attribute_short?(attribute)
      public_send(attribute).length < 5
    end
end

irb> person = Person.new
irb> person.name = "Joe Doe"
irb> person.name
=> "Joe Doe"

# `full_name` is the alias for `name`, and returns the same value
irb> person.full_name
=> "Joe Doe"
irb> person.name_short?
=> false

# `full_name_short?` is the alias for `name_short?`, and returns the same value
irb> person.full_name_short?
=> false

1.6 回呼

ActiveModel::Callbacks 為普通的 Ruby 物件提供 Active Record 風格的回呼。這些回呼允許您掛鉤到模型的生命週期事件，例如 before_update 和 after_create，以及定義在模型生命週期中的特定點執行的自訂邏輯。

您可以按照以下步驟實作 ActiveModel::Callbacks：

在您的類別中擴展 ActiveModel::Callbacks。
使用 define_model_callbacks 建立應該具有關聯回呼的方法清單。當您指定一個方法，例如 :update 時，它將自動包含 :update 事件的所有三個預設回呼（before、around 和 after）。
在定義的方法內部，使用 run_callbacks，當觸發特定事件時，它將執行回呼鏈。
在您的類別中，您可以像在 Active Record 模型中一樣使用 before_update、after_update 和 around_update 方法。

class Person
  extend ActiveModel::Callbacks

  define_model_callbacks :update

  before_update :reset_me
  after_update :finalize_me
  around_update :log_me

  # `define_model_callbacks` method containing `run_callbacks` which runs the callback(s) for the given event
  def update
    run_callbacks(:update) do
      puts "update method called"
    end
  end

  private
    # When update is called on an object, then this method is called by `before_update` callback
    def reset_me
      puts "reset_me method: called before the update method"
    end

    # When update is called on an object, then this method is called by `after_update` callback
    def finalize_me
      puts "finalize_me method: called after the update method"
    end

    # When update is called on an object, then this method is called by `around_update` callback
    def log_me
      puts "log_me method: called around the update method"
      yield
      puts "log_me method: block successfully called"
    end
end

上面的類別將產生以下輸出，指示回呼被呼叫的順序：

irb> person = Person.new
irb> person.update
reset_me method: called before the update method
log_me method: called around the update method
update method called
log_me method: block successfully called
finalize_me method: called after the update method
=> nil

如上面的範例所示，當定義「around」回呼時，請記住要 yield 到區塊，否則它將不會被執行。

傳遞給 define_model_callbacks 的 method_name 不得包含結尾的 !、? 或 =。此外，多次定義相同的回呼將會覆寫先前的回呼定義。

1.6.1 定義特定的回呼

您可以選擇透過將 only 選項傳遞給 define_model_callbacks 方法來建立特定的回呼。

define_model_callbacks :update, :create, only: [:after, :before]

這將只建立 before_create / after_create 和 before_update / after_update 回呼，但跳過 around_* 回呼。該選項將適用於在該方法呼叫上定義的所有回呼。可以多次呼叫 define_model_callbacks 以指定不同的生命週期事件。

define_model_callbacks :create, only: :after
define_model_callbacks :update, only: :before
define_model_callbacks :destroy, only: :around

這將僅建立 after_create、before_update 和 around_destroy 方法。

1.6.2 使用類別定義回呼

您可以將一個類別傳遞給 before_<type>、after_<type> 和 around_<type>，以便更精確地控制回呼的觸發時間和環境。回呼將觸發該類別的 <action>_<type> 方法，並將該類別的實例作為引數傳遞。

class Person
  extend ActiveModel::Callbacks

  define_model_callbacks :create
  before_create PersonCallbacks
end

class PersonCallbacks
  def self.before_create(obj)
    # `obj` is the Person instance that the callback is being called on
  end
end

1.6.3 中止回呼

可以透過拋出 :abort 來在任何時間點中止回呼鏈。這與 Active Record 回呼的工作方式類似。

在下面的範例中，由於我們在 reset_me 方法中在更新之前拋出 :abort，因此其餘的回呼鏈（包括 before_update）將被中止，並且 update 方法的主體將不會被執行。

class Person
  extend ActiveModel::Callbacks

  define_model_callbacks :update

  before_update :reset_me
  after_update :finalize_me
  around_update :log_me

  def update
    run_callbacks(:update) do
      puts "update method called"
    end
  end

  private
    def reset_me
      puts "reset_me method: called before the update method"
      throw :abort
      puts "reset_me method: some code after abort"
    end

    def finalize_me
      puts "finalize_me method: called after the update method"
    end

    def log_me
      puts "log_me method: called around the update method"
      yield
      puts "log_me method: block successfully called"
    end
end

irb> person = Person.new

irb> person.update
reset_me method: called before the update method
=> false

1.7 轉換

ActiveModel::Conversion 是一組方法，可讓您將物件轉換為不同形式以用於不同目的。常見的用例是將物件轉換為字串或整數，以建立 URL、表單欄位等等。

ActiveModel::Conversion 模組將以下方法：to_model、to_key、to_param 和 to_partial_path 添加到類別中。

方法的返回值取決於是否定義了 persisted? 以及是否提供了 id。如果物件已儲存到資料庫或儲存區，則 persisted? 方法應返回 true，否則應返回 false。如果物件未儲存，則 id 應引用物件的 id 或 nil。

class Person
  include ActiveModel::Conversion
  attr_accessor :id

  def initialize(id)
    @id = id
  end

  def persisted?
    id.present?
  end
end

1.7.1 to_model

to_model 方法返回物件本身。

irb> person = Person.new(1)
irb> person.to_model == person
=> true

如果您的模型不像 Active Model 物件那樣運作，那麼您應該自行定義 :to_model，返回一個代理物件，該物件使用符合 Active Model 的方法來包裝您的物件。

class Person
  def to_model
    # A proxy object that wraps your object with Active Model compliant methods.
    PersonModel.new(self)
  end
end

1.7.2 to_key

如果設定了任何屬性，則 to_key 方法會傳回物件的鍵屬性陣列，無論物件是否持久化。如果沒有鍵屬性，則傳回 nil。

irb> person.to_key
=> [1]

鍵屬性是用於識別物件的屬性。例如，在資料庫支援的模型中，鍵屬性是主鍵。

1.7.3 to_param

to_param 方法返回物件的鍵的 string 表示形式，適用於 URL，或者在 persisted? 為 false 的情況下返回 nil。

irb> person.to_param
=> "1"

1.7.4 to_partial_path

to_partial_path 方法返回一個表示物件關聯路徑的 string。Action Pack 使用此方法來尋找適合表示物件的部分。

irb> person.to_partial_path
=> "people/person"

1.8 Dirty

ActiveModel::Dirty 對於追蹤模型屬性在儲存之前所做的變更很有用。此功能可讓您判斷哪些屬性已修改、它們的先前值和目前值是什麼，並根據這些變更執行動作。它對於應用程式內的稽核、驗證和條件邏輯特別方便。它提供了一種以與 Active Record 相同的方式追蹤物件中的變更的方法。

當物件的屬性發生一或多項變更且尚未儲存時，物件會變成 Dirty。它具有基於屬性的存取器方法。

若要使用 ActiveModel::Dirty，您需要：

在您的類別中引入該模組。
使用 define_attribute_methods 定義您想要追蹤變更的屬性方法。
在每次變更追蹤的屬性之前呼叫 [attr_name]_will_change!。
在變更持久化後呼叫 changes_applied。
當您想要重設變更資訊時，請呼叫 clear_changes_information。
當您想要還原先前的資料時，請呼叫 restore_attributes。

然後，您可以使用 ActiveModel::Dirty 提供的方法查詢物件的所有已變更屬性清單、已變更屬性的原始值，以及對屬性所做的變更。

讓我們考慮一個具有屬性 first_name 和 last_name 的 Person 類別，並判斷我們如何使用 ActiveModel::Dirty 來追蹤對這些屬性的變更。

class Person
  include ActiveModel::Dirty

  attr_reader :first_name, :last_name
  define_attribute_methods :first_name, :last_name

  def initialize
    @first_name = nil
    @last_name = nil
  end

  def first_name=(value)
    first_name_will_change! unless value == @first_name
    @first_name = value
  end

  def last_name=(value)
    last_name_will_change! unless value == @last_name
    @last_name = value
  end

  def save
    # Persist data - clears dirty data and moves `changes` to `previous_changes`.
    changes_applied
  end

  def reload!
    # Clears all dirty data: current changes and previous changes.
    clear_changes_information
  end

  def rollback!
    # Restores all previous data of the provided attributes.
    restore_attributes
  end
end

1.8.1 直接查詢物件的所有已變更屬性清單

irb> person = Person.new

# A newly instantiated `Person` object is unchanged:
irb> person.changed?
=> false

irb> person.first_name = "Jane Doe"
irb> person.first_name
=> "Jane Doe"

如果任何屬性有未儲存的變更，則 changed? 返回 true，否則返回 false。

irb> person.changed?
=> true

changed 返回一個包含未儲存變更屬性名稱的陣列。

irb> person.changed
=> ["first_name"]

changed_attributes 返回一個包含未儲存變更屬性的雜湊，指示它們的原始值，例如 attr => 原始值。

irb> person.changed_attributes
=> {"first_name" => nil}

changes 返回一個變更雜湊，以屬性名稱作為鍵，以原始值和新值的陣列作為值，例如 attr => [原始值, 新值]。

irb> person.changes
=> {"first_name" => [nil, "Jane Doe"]}

previous_changes 返回一個雜湊，其中包含在儲存模型之前（即在呼叫 changes_applied 之前）已變更的屬性。

irb> person.previous_changes
=> {}

irb> person.save
irb> person.previous_changes
=> {"first_name" => [nil, "Jane Doe"]}

1.8.2 基於屬性的存取器方法

irb> person = Person.new

irb> person.changed?
=> false

irb> person.first_name = "John Doe"
irb> person.first_name
=> "John Doe"

[attr_name]_changed? 檢查特定屬性是否已變更。

irb> person.first_name_changed?
=> true

[attr_name]_was 追蹤屬性的先前值。

irb> person.first_name_was
=> nil

[attr_name]_change 追蹤已變更屬性的先前值和目前值。如果已變更，則返回包含 [原始值, 新值] 的陣列，否則返回 nil。

irb> person.first_name_change
=> [nil, "John Doe"]
irb> person.last_name_change
=> nil

[attr_name]_previously_changed? 檢查特定屬性是否在儲存模型之前（即在呼叫 changes_applied 之前）已變更。

irb> person.first_name_previously_changed?
=> false
irb> person.save
irb> person.first_name_previously_changed?
=> true

[attr_name]_previous_change 追蹤已變更屬性的先前值和目前值，在儲存模型之前（即在呼叫 changes_applied 之前）。如果已變更，則返回包含 [原始值, 新值] 的陣列，否則返回 nil。

irb> person.first_name_previous_change
=> [nil, "John Doe"]

1.9 命名

ActiveModel::Naming 添加了一個類別方法和輔助方法，使命名和路由更易於管理。該模組定義了 model_name 類別方法，該方法將使用一些 ActiveSupport::Inflector 方法定義多個存取器。

class Person
  extend ActiveModel::Naming
end

name 返回模型的名稱。

irb> Person.model_name.name
=> "Person"

singular 返回記錄或類別的單數類別名稱。

irb> Person.model_name.singular
=> "person"

plural 返回記錄或類別的複數類別名稱。

irb> Person.model_name.plural
=> "people"

element 移除命名空間，並返回單數的蛇底命名名稱。它通常由 Action Pack 和/或 Action View 輔助方法使用，以幫助呈現部分/表單的名稱。

irb> Person.model_name.element
=> "person"

human 使用 I18n 將模型名稱轉換為更人性化的格式。預設情況下，它會使用底線，然後將類別名稱人性化。

irb> Person.model_name.human
=> "Person"

collection 移除命名空間，並返回複數的蛇底命名名稱。它通常由 Action Pack 和/或 Action View 輔助方法使用，以幫助呈現部分/表單的名稱。

irb> Person.model_name.collection
=> "people"

param_key 返回用於參數名稱的字串。

irb> Person.model_name.param_key
=> "person"

i18n_key 返回 i18n 金鑰的名稱。它使用底線表示模型名稱，然後將其作為符號返回。

irb> Person.model_name.i18n_key
=> :person

route_key 返回在產生路由名稱時使用的字串。

irb> Person.model_name.route_key
=> "people"

singular_route_key 返回在產生路由名稱時使用的字串。

irb> Person.model_name.singular_route_key
=> "person"

uncountable? 識別記錄或類別的類別名稱是否為不可數。

irb> Person.model_name.uncountable?
=> false

某些 Naming 方法（例如 param_key、route_key 和 singular_route_key）對於命名空間模型會有所不同，具體取決於它是否在隔離的引擎內。

1.9.1 自訂模型的名稱

有時候您可能想要自訂在表單輔助方法和 URL 生成中使用的模型名稱。當您想要為模型使用更易於使用者理解的名稱，同時仍能使用其完整的命名空間來參照它時，這會很有用。

例如，假設您的 Rails 應用程式中有一個 Person 命名空間，並且您想要為新的 Person::Profile 建立表單。

預設情況下，Rails 會產生 URL 為 /person/profiles 的表單，其中包含命名空間 person。但是，如果您希望 URL 單純指向 profiles 而不帶命名空間，您可以像這樣自訂 model_name 方法

module Person
  class Profile
    include ActiveModel::Model

    def self.model_name
      ActiveModel::Name.new(self, nil, "Profile")
    end
  end
end

透過此設定，當您使用 form_with 輔助方法來為建立新的 Person::Profile 建立表單時，Rails 將產生 URL 為 /profiles 而不是 /person/profiles 的表單，因為 model_name 方法已被覆寫以返回 Profile。

此外，路徑輔助方法將在不包含命名空間的情況下產生，因此您可以使用 profiles_path 而不是 person_profiles_path 來產生 profiles 資源的 URL。若要使用 profiles_path 輔助方法，您需要在 config/routes.rb 檔案中為 Person::Profile 模型定義路由，如下所示

Rails.application.routes.draw do
  resources :profiles
end

因此，您可以預期模型會針對上一節中描述的方法傳回以下值

irb> name = ActiveModel::Name.new(Person::Profile, nil, "Profile")
=> #<ActiveModel::Name:0x000000014c5dbae0

irb> name.singular
=> "profile"
irb> name.singular_route_key
=> "profile"
irb> name.route_key
=> "profiles"

1.10 SecurePassword

ActiveModel::SecurePassword 提供一種以加密形式安全儲存任何密碼的方式。當您包含此模組時，會提供一個 has_secure_password 類別方法，該方法會預設定義一個帶有特定驗證的 password 存取器。

ActiveModel::SecurePassword 依賴於 bcrypt，因此請將此 gem 包含在您的 Gemfile 中以使用它。

gem "bcrypt"

ActiveModel::SecurePassword 要求您具有 password_digest 屬性。

以下驗證會自動新增

密碼在建立時必須存在。
密碼確認（使用 password_confirmation 屬性）。
密碼的最大長度為 72 位元組（bcrypt 在加密之前會將字串截斷至此大小，因此這是必需的）。

如果不需要密碼確認驗證，只需省略 password_confirmation 的值（即，不要為其提供表單欄位）。當此屬性具有 nil 值時，將不會觸發驗證。

為了進一步自訂，可以傳遞 validations: false 作為參數來抑制預設驗證。

class Person
  include ActiveModel::SecurePassword

  has_secure_password
  has_secure_password :recovery_password, validations: false

  attr_accessor :password_digest, :recovery_password_digest
end

irb> person = Person.new

# When password is blank.
irb> person.valid?
=> false

# When the confirmation doesn't match the password.
irb> person.password = "aditya"
irb> person.password_confirmation = "nomatch"
irb> person.valid?
=> false

# When the length of password exceeds 72.
irb> person.password = person.password_confirmation = "a" * 100
irb> person.valid?
=> false

# When only password is supplied with no password_confirmation.
irb> person.password = "aditya"
irb> person.valid?
=> true

# When all validations are passed.
irb> person.password = person.password_confirmation = "aditya"
irb> person.valid?
=> true

irb> person.recovery_password = "42password"

# `authenticate` is an alias for `authenticate_password`
irb> person.authenticate("aditya")
=> #<Person> # == person
irb> person.authenticate("notright")
=> false
irb> person.authenticate_password("aditya")
=> #<Person> # == person
irb> person.authenticate_password("notright")
=> false

irb> person.authenticate_recovery_password("aditya")
=> false
irb> person.authenticate_recovery_password("42password")
=> #<Person> # == person
irb> person.authenticate_recovery_password("notright")
=> false

irb> person.password_digest
=> "$2a$04$gF8RfZdoXHvyTjHhiU4ZsO.kQqV9oonYZu31PRE4hLQn3xM2qkpIy"
irb> person.recovery_password_digest
=> "$2a$04$iOfhwahFymCs5weB3BNH/uXkTG65HR.qpW.bNhEjFP3ftli3o5DQC"

1.11 序列化

ActiveModel::Serialization 為您的物件提供基本的序列化。您需要宣告一個包含您要序列化的屬性的屬性雜湊。屬性必須是字串，而不是符號。

class Person
  include ActiveModel::Serialization

  attr_accessor :name, :age

  def attributes
    # Declaration of attributes that will be serialized
    { "name" => nil, "age" => nil }
  end

  def capitalized_name
    # Declared methods can be later included in the serialized hash
    name&.capitalize
  end
end

現在，您可以使用 serializable_hash 方法存取您物件的序列化雜湊。serializable_hash 的有效選項包括 :only、:except、:methods 和 :include。

irb> person = Person.new

irb> person.serializable_hash
=> {"name" => nil, "age" => nil}

# Set the name and age attributes and serialize the object
irb> person.name = "bob"
irb> person.age = 22
irb> person.serializable_hash
=> {"name" => "bob", "age" => 22}

# Use the methods option to include the capitalized_name method
irb>  person.serializable_hash(methods: :capitalized_name)
=> {"name" => "bob", "age" => 22, "capitalized_name" => "Bob"}

# Use the only method to include only the name attribute
irb> person.serializable_hash(only: :name)
=> {"name" => "bob"}

# Use the except method to exclude the name attribute
irb> person.serializable_hash(except: :name)
=> {"age" => 22}

使用 includes 選項的範例需要更複雜的場景，如下所示

  class Person
    include ActiveModel::Serialization
    attr_accessor :name, :notes # Emulate has_many :notes

    def attributes
      { "name" => nil }
    end
  end

  class Note
    include ActiveModel::Serialization
    attr_accessor :title, :text

    def attributes
      { "title" => nil, "text" => nil }
    end
  end

irb> note = Note.new
irb> note.title = "Weekend Plans"
irb> note.text = "Some text here"

irb> person = Person.new
irb> person.name = "Napoleon"
irb> person.notes = [note]

irb> person.serializable_hash
=> {"name" => "Napoleon"}

irb> person.serializable_hash(include: { notes: { only: "title" }})
=> {"name" => "Napoleon", "notes" => [{"title" => "Weekend Plans"}]}

1.11.1 ActiveModel::Serializers::JSON

Active Model 也提供 ActiveModel::Serializers::JSON 模組用於 JSON 序列化/反序列化。

若要使用 JSON 序列化，請將您要包含的模組從 ActiveModel::Serialization 變更為 ActiveModel::Serializers::JSON。它已經包含前者，因此不需要明確包含它。

class Person
  include ActiveModel::Serializers::JSON

  attr_accessor :name

  def attributes
    { "name" => nil }
  end
end

與 serializable_hash 類似的 as_json 方法，會提供一個雜湊來表示模型，其鍵為字串。to_json 方法會傳回代表模型的 JSON 字串。

irb> person = Person.new

# A hash representing the model with its keys as a string
irb> person.as_json
=> {"name" => nil}

# A JSON string representing the model
irb> person.to_json
=> "{\"name\":null}"

irb> person.name = "Bob"
irb> person.as_json
=> {"name" => "Bob"}

irb> person.to_json
=> "{\"name\":\"Bob\"}"

您也可以從 JSON 字串定義模型的屬性。為此，請先在您的類別中定義 attributes= 方法

class Person
  include ActiveModel::Serializers::JSON

  attr_accessor :name

  def attributes=(hash)
    hash.each do |key, value|
      public_send("#{key}=", value)
    end
  end

  def attributes
    { "name" => nil }
  end
end

現在可以使用 from_json 建立 Person 的實例並設定屬性。

irb> json = { name: "Bob" }.to_json
=> "{\"name\":\"Bob\"}"

irb> person = Person.new

irb> person.from_json(json)
=> #<Person:0x00000100c773f0 @name="Bob">

irb> person.name
=> "Bob"

1.12 翻譯

ActiveModel::Translation 提供您的物件與 Rails 國際化 (i18n) 框架之間的整合。

class Person
  extend ActiveModel::Translation
end

透過 human_attribute_name 方法，您可以將屬性名稱轉換為更易於使用者理解的格式。易於使用者理解的格式定義在您的地區設定檔案中。

# config/locales/app.pt-BR.yml
pt-BR:
  activemodel:
    attributes:
      person:
        name: "Nome"

irb> Person.human_attribute_name("name")
=> "Name"

irb> I18n.locale = :"pt-BR"
=> :"pt-BR"
irb> Person.human_attribute_name("name")
=> "Nome"

1.13 驗證

ActiveModel::Validations 新增驗證物件的功能，這對於確保應用程式內部的資料完整性和一致性非常重要。透過將驗證納入您的模型中，您可以定義規則來管理屬性值的正確性，並防止無效資料。

class Person
  include ActiveModel::Validations

  attr_accessor :name, :email, :token

  validates :name, presence: true
  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
  validates! :token, presence: true
end

irb> person = Person.new
irb> person.token = "2b1f325"
irb> person.valid?
=> false

irb> person.name = "Jane Doe"
irb> person.email = "me"
irb> person.valid?
=> false

irb> person.email = "jane.doe@gmail.com"
irb> person.valid?
=> true

# `token` uses validate! and will raise an exception when not set.
irb> person.token = nil
irb> person.valid?
=> "Token can't be blank (ActiveModel::StrictValidationFailed)"

1.13.1 驗證方法和選項

您可以使用以下某些方法新增驗證

validate：透過方法或區塊將驗證新增至類別。
validates：屬性可以傳遞給 validates 方法，它提供所有預設驗證器的捷徑。
validates! 或設定 strict: true：用於定義最終使用者無法更正，並且被認為是例外的驗證。當驗證失敗時，使用驚嘆號或將 :strict 選項設定為 true 定義的每個驗證器都會始終引發 ActiveModel::StrictValidationFailed，而不是將錯誤新增至錯誤中。
validates_with：將記錄傳遞給指定的類別或類別，並允許它們根據更複雜的條件新增錯誤。
validates_each：針對區塊驗證每個屬性。

以下某些選項可以與特定的驗證器一起使用。若要判斷您正在使用的選項是否可以與特定的驗證器一起使用，請閱讀驗證文件。

:on：指定新增驗證的環境。您可以傳遞符號或符號陣列。（例如，on: :create 或 on: :custom_validation_context 或 on: [:create, :custom_validation_context]）。沒有 :on 選項的驗證無論環境為何都會執行。具有某些 :on 選項的驗證只會在指定的環境中執行。您可以在使用 valid?(:context) 進行驗證時傳遞環境。
:if：指定要呼叫的方法、proc 或字串，以判斷是否應發生驗證（例如，if: :allow_validation，或 if: -> { signup_step > 2 }）。方法、proc 或字串應傳回或評估為 true 或 false 值。
:unless：指定要呼叫的方法、proc 或字串，以判斷是否不應發生驗證（例如，unless: :skip_validation，或 unless: Proc.new { |user| user.signup_step <= 2 }）。方法、proc 或字串應傳回或評估為 true 或 false 值。
:allow_nil：如果屬性為 nil，則跳過驗證。
:allow_blank：如果屬性為空白，則跳過驗證。
:strict：如果 :strict 選項設定為 true，則會引發 ActiveModel::StrictValidationFailed，而不是新增錯誤。:strict 選項也可以設定為任何其他例外狀況。

在相同方法上多次呼叫 validate 會覆寫先前的定義。

1.13.2 錯誤

ActiveModel::Validations 會自動將 errors 方法新增至您使用新的 ActiveModel::Errors 物件初始化的實例，因此您不需要手動執行此操作。

在物件上執行 valid? 來檢查物件是否有效。如果物件無效，它會傳回 false，並且錯誤將新增至 errors 物件。

irb> person = Person.new

irb> person.email = "me"
irb> person.valid?
=> # Raises Token can't be blank (ActiveModel::StrictValidationFailed)

irb> person.errors.to_hash
=> {:name => ["can't be blank"], :email => ["is invalid"]}

irb> person.errors.full_messages
=> ["Name can't be blank", "Email is invalid"]

1.14 Lint 測試

ActiveModel::Lint::Tests 允許您測試物件是否符合 Active Model API。透過在您的 TestCase 中包含 ActiveModel::Lint::Tests，它將包含測試，告訴您您的物件是否完全符合規範，或者如果不符合，則會告知您 API 的哪些方面未實作。

這些測試不會嘗試判斷傳回值的語意正確性。例如，您可以實作 valid? 以始終傳回 true，並且測試將會通過。您有責任確保這些值在語意上是有意義的。

您傳入的物件預期會從對 to_model 的呼叫中傳回符合規範的物件。to_model 傳回 self 是完全沒有問題的。

app/models/person.rb

class Person
  include ActiveModel::API
end

test/models/person_test.rb

require "test_helper"

class PersonTest < ActiveSupport::TestCase
  include ActiveModel::Lint::Tests

  setup do
    @model = Person.new
  end
end

請參閱測試方法文件以取得更多詳細資訊。

若要執行測試，您可以使用以下命令

$ bin/rails test

Run options: --seed 14596

# Running:

......

Finished in 0.024899s, 240.9735 runs/s, 1204.8677 assertions/s.

6 runs, 30 assertions, 0 failures, 0 errors, 0 skips