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

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

class Customer < ActiveRecord::Base
  composed_of :balance, class_name: "Money", mapping: %w(amount currency)
  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, если сортировка имеет смысл). Это отличается от объектов сущностей, где равенство определяется по идентичности. Класс сущности, такой как Клиент, может легко иметь два разных объекта, у которых оба есть адрес на улице Гайанцинведж. Идентичность сущности определяется уникальными идентификаторами объекта или отношения (такими как первичные ключи). Обычные классы 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 для модели, записи можно загружать из базы данных, указав экземпляр объекта значения в хеше условий. В следующем примере находятся все клиенты с balance_amount равным 20 и balance_currency равным «USD»:

Customer.where(balance: Money.new(20, "USD"))