модуль ActiveRecord::Aggregations::ClassMethods

Active Record реализует агрегацию с помощью макро-подобного класса метода, называемого composed_of, для представления атрибутов как объектов значений. Он выражает отношения, такие как «Счет [составлен из] Денег [среди прочего]» или «Человек [составлен из] [адреса]». Каждый вызов макроса добавляет описание того, как объекты значений создаются из атрибутов объекта сущности (когда сущность инициализируется как новый объект или из поиска существующего объекта) и как их можно преобразовать обратно в атрибуты (когда сущность сохраняется в базе данных).

class Customer < ActiveRecord::Base
  composed_of :balance, class_name: "Money", mapping: %w(balance amount)
  composed_of :address, mapping: [ %w(address_street street), %w(address_city city) ]
end

Теперь класс клиента имеет следующие методы для работы с объектами значений:

• Customer#balance, Customer#balance=(money)

• Customer#address, Customer#address=(address)

Эти методы будут работать с объектами значений, такими как описанные ниже:

class Money
  include Comparable
  attr_reader :amount, :currency
  EXCHANGE_RATES = { "USD_TO_DKK" => 6 }

  def initialize(amount, currency = "USD")
    @amount, @currency = amount, currency
  end

  def exchange_to(other_currency)
    exchanged_amount = (amount * EXCHANGE_RATES["#{currency}_TO_#{other_currency}"]).floor
    Money.new(exchanged_amount, other_currency)
  end

  def ==(other_money)
    amount == other_money.amount && currency == other_money.currency
  end

  def <=>(other_money)
    if currency == other_money.currency
      amount <=> other_money.amount
    else
      amount <=> other_money.exchange_to(currency).amount
    end
  end
end

class Address
  attr_reader :street, :city
  def initialize(street, city)
    @street, @city = street, city
  end

  def close_to?(other_address)
    city == other_address.city
  end

  def ==(other_address)
    city == other_address.city && street == other_address.street
  end
end

Теперь можно получить доступ к атрибутам из базы данных через объекты значений. Если вы выберите назвать композицию так же, как атрибут, это будет единственный способ получить доступ к этому атрибуту. Так обстоит дело с нашим атрибутом balance. Вы взаимодействуете с объектами значений так же, как с любым другим атрибутом:

customer.balance = Money.new(20)     # sets the Money value object and the attribute
customer.balance                     # => Money value object
customer.balance.exchange_to("DKK")  # => Money.new(120, "DKK")
customer.balance > Money.new(10)     # => true
customer.balance == Money.new(20)    # => true
customer.balance < Money.new(5)      # => false

Объекты значений также могут состоять из нескольких атрибутов, как в случае с адресом. Порядок сопоставлений определит порядок параметров.

customer.address_street = "Hyancintvej"
customer.address_city   = "Copenhagen"
customer.address        # => Address.new("Hyancintvej", "Copenhagen")

customer.address = Address.new("May Street", "Chicago")
customer.address_street # => "May Street"
customer.address_city   # => "Chicago"

Создание объектов значений

Объекты значений — это неизменяемые и взаимозаменяемые объекты, представляющие данное значение, например, объект Money, представляющий 5 долларов. Два объекта Money, оба представляющих 5 долларов, должны быть равны (через методы, такие как == и <=> из Comparable, если ранжирование имеет смысл). Это отличается от объектов сущностей, где равенство определяется тождеством. Класс сущности, такой как Customer, может легко иметь два разных объекта, оба с адресом на Hyancintvej. Тождество сущности определяется объектом или реляционными уникальными идентификаторами (например, первичными ключами). Обычные классы ActiveRecord::Base являются объектами сущностей.

Также важно рассматривать объекты значений как неизменяемые. Не позволяйте объекту Money изменять свою сумму после создания. Создайте новый объект Money с новым значением вместо этого. Метод Money#exchange_to является примером этого. Он возвращает новый объект значения вместо изменения собственных значений. Active Record не будет сохранять объекты значений, изменённые другими способами, кроме метода записи.

Требование неизменяемости обеспечивается Active Record путём заморозки любого объекта, назначенного как объект значения. Попытка изменить его позже приведёт к RuntimeError.

Узнайте больше об объектах значений на c2.com/cgi/wiki?ValueObject и об опасностях, связанных с тем, чтобы объекты значений не были неизменяемыми, на c2.com/cgi/wiki?ValueObjectsShouldBeImmutable

Настраиваемые конструкторы и преобразователи

По умолчанию объекты значений инициализируются вызовом конструктора класса значений new, передавая каждый из сопоставленных атрибутов в порядке, заданном параметром :mapping, в качестве аргументов. Если класс значений не поддерживает эту конвенцию, composed_of позволяет указать настраиваемый конструктор.

Когда новому значению присваивается объект значения, по умолчанию предполагается, что новое значение является экземпляром класса значения. Указание настраиваемого преобразователя позволяет автоматически преобразовать новое значение в экземпляр класса значения, если это необходимо.

Например, модель NetworkResource имеет атрибуты network_address и cidr_range, которые должны агрегироваться с использованием класса значений NetAddr::CIDR (www.rubydoc.info/gems/netaddr/1.5.0/NetAddr/CIDR). Конструктор класса значений называется create и ожидает строку адреса CIDR в качестве параметра. Новые значения можно присвоить объекту значения, используя другой объект NetAddr::CIDR, строку или массив. Параметры :constructor и :converter могут использоваться для удовлетворения этих требований:

class NetworkResource < ActiveRecord::Base
  composed_of :cidr,
              class_name: 'NetAddr::CIDR',
              mapping: [ %w(network_address network), %w(cidr_range bits) ],
              allow_nil: true,
              constructor: Proc.new { |network_address, cidr_range| NetAddr::CIDR.create("#{network_address}/#{cidr_range}") },
              converter: Proc.new { |value| NetAddr::CIDR.create(value.is_a?(Array) ? value.join('/') : value) }
end

# This calls the :constructor
network_resource = NetworkResource.new(network_address: '192.168.0.1', cidr_range: 24)

# These assignments will both use the :converter
network_resource.cidr = [ '192.168.2.1', 8 ]
network_resource.cidr = '192.168.0.1/24'

# This assignment won't use the :converter as the value is already an instance of the value class
network_resource.cidr = NetAddr::CIDR.create('192.168.2.1/8')

# Saving and then reloading will use the :constructor on reload
network_resource.save
network_resource.reload

Поиск записей по объекту значения

После указания отношения composed_of для модели записи можно загрузить из базы данных, указав экземпляр объекта значения в хэше условий. Следующий пример находит всех клиентов, у которых address_street равно «May Street» и address_city равно «Chicago»:

Customer.where(address: Address.new("May Street", "Chicago"))