Building Rich Domain Models in Rails. Separating Persistence.

Abstract

Domain model is an effective tool for software development. It can be used to express really complex business logic, and to verify and validate the understanding of the domain among stakeholders. Building rich domain models in Rails is hard. Primarily, because of Active Record, which doesn’t play well with the domain model approach. One way to deal with this problem is to use an ORM implementing the data mapper pattern. Unfortunately, there is no production ready ORM doing that for Ruby. DataMapper 2 is going to be the first one. Another way is to use Active Record as just a persistence mechanism and build a rich domain model on top of it. That’s what I’m going to talk about in this article.

Problems with Active Record

First, let’s take a look at some problems caused by using a class extending Active Record for expressing a domain concept:

• The class is aware of Active Record. Therefore, you need to load Active Record to run your tests.
• An instance of the class is responsible for saving and updating itself. This makes mocking and stubbing harder.
• Every instance exposes such low-level methods as ‘update_attribute!’. They give you too much power to change the internal state of objects. Power corrupts, which is why you see ‘update_attributes’ used in so many places.
• “Has many” associations allow bypassing an aggregate root. Too much power, and as we all know, it corrupts.
• Every instance is responsible for validating itself. It’s hard to test. On top of that, it makes validations much harder to compose.

Solution

Following Rich Hickey’s motto of splitting things apart, the best solution I see is to split every Active Record class into three different classes:

• Entity
• Data Object
• Repository

The core idea here is that every entity when instantiated is given a data object. The entity delegates its fields’ access to the data object. The data object doesn’t have to be an Active Record object. You can always provide a stub or an OpenStruct instead. Since the entity is a plain old ruby object, it doesn’t know how to save/validate/update itself. It also doesn’t know how to fetch itself from the database. A repository is responsible for fetching data objects from the database and constructing entities. It is also responsible for creating and updating entities. To cope with its responsibilities the repository has to know how to map data objects to entities. A registry of all data objects and their correspondent entities is created to do exactly that.

Example

Let’s take a look at a practical application of this approach. Order and Item are two entities that form an aggregate.

Step 1: Schema

This is the schema we can use to store them in the database:

create_table "orders", :force => true do |t|
  t.decimal  "amount"
  t.date     "deliver_at"
  t.datetime "created_at", :null => false
  t.datetime "updated_at", :null => false
end

create_table "items", :force => true do |t|
  t.string   "name"
  t.decimal  "amount"
  t.integer  "order_id"
  t.datetime "created_at", :null => false
  t.datetime "updated_at", :null => false
end

As you can see we don’t have to adapt the schema for our approach.

Step 2: Define Data Objects

class OrderData < ActiveRecord::Base
  self.table_name = "orders"

  attr_accessible :amount, :deliver_at

  validates :amount, numericality: true
  has_many :items, class_name: "ItemData", foreign_key: "order_id"
end

class ItemData < ActiveRecord::Base
  self.table_name = "items"

  attr_accessible :amount, :name

  validates :amount, numericality: true
  validates :name, presence: true
end

Step 3: Define Domain Objects

All entities are plain old ruby objects including the Model module:

class Order
  include Edr::Model

  # Delegates id, id=, amount, amount=, deliver_at, deliver_at to the data object
  fields :id, :amount, :deliver_at

   # ...
end

class Item
  include Edr::Model
  fields :id, :amount, :name
end

Step 4: Map Domain Objects to Data Objects

The next step is to map entities to corresponding data objects:

Edr::Registry.define do
  map Order, OrderData
  map Item, ItemData
end

Step 5: Implement Repository

As the Order and Item classes form an aggregate, we can get a reference to an item only through its order. Therefore, we need to implement only one repository:

module OrderRepository
  extend Edr::AR::Repository
  set_model_class Order

  def self.find_by_amount amount
    where(amount: amount)
  end
end

Now, let’s see how we can use all these classes in an application.

describe "Persisting objects" do
  example do
    order = Order.new amount: 10

    OrderRepository.persist order

    order.id.should be_present
    order.amount.should == 10
  end

  it "persists an aggregate with children" do
    order = Order.new amount: 10
    order.add_item name: 'item1', amount: 5

    OrderRepository.persist order

    from_db = OrderRepository.find(order.id)
    from_db.items.first.amount.should == 5
  end
end

describe "Selecting models" do
  let!(:data){OrderData.create! amount: 10, deliver_at: Date.today}

  example do
    orders = OrderRepository.find_by_amount 10
    orders.first.id == data.id
  end

  it "finds by id" do
    order = OrderRepository.find data.id
    order.id.should == data.id
  end

  it "returns all saved objects" do
    orders = OrderRepository.all
    orders.first.id == data.id
  end

  it "raises an exception when cannot find cannot object" do
    ->{OrderRepository.find 999}.should raise_error
  end
end

Associations

One important aspect of building rich domain models hasn’t been covered yet. How are the associations between an aggregate root and its children managed? How do we access items? There are two options available. This first is to use the ‘association’ and ‘wrap’ helper methods.

class Order
  include Edr::Model

  fields :id, :amount, :deliver_at
  wrap_associations :items

  def add_item attrs
    wrap association(:items).new(attrs)
  end
end

The association method returns the data object’s association. In our case, it’s a has-many. The wrap method transforms a collection of data objects into a collection of models. Every entity has a reference to the repository that created it which provides the other option of managing associations.

class Order
  include Edr::Model

  fields :id, :amount, :deliver_at

  def add_item attrs
    repository.create_item self, attrs
  end
end

Validations

Since data objects are hidden, and aren’t supposed to be accessed directly by the client code, we need to change the way we run validations. There are lots of available options, one of which is the following:

module DataValidator
  def self.validate model
    data = model._data
    data.valid?
    data.errors.full_messages
  end
end

Here’s how you’d use it in the code:

order_data = OrderData.create! amount: 10, deliver_at: Date.today
order = Order.new(order_data)
order.amount = "blah"
Edr::AR::DataValidator.validate(order).should be_present

You don’t have to return an array of strings. It can be a hash or even a special object. The idea here is to separate entities from their validations. Once again, by splitting things apart we end up with a better design. Why? For one thing, we can compose validations in run time based on, for instance, user settings. For another thing, we can validate a group of objects together, so there is no need to copy errors from one object to another.

Architecture

Separating persistence from domain model has a tremendous impact on the architecture of our applications. The following is the traditional Rails app architecture.

Image may be NSFW.
Clik here to view.

That’s what we get if we separate persistence.

Image may be NSFW.
Clik here to view.

You don’t have to be one of the Three Amigos to see the flaws of the traditional Rails app architecture: the domain classes depend on the database and Rails. Whereas, the architecture illustrated by the second diagram doesn’t have these flaws, which allows us to keep the domain logic abstract and framework agnostic.

What we got

• The persistence logic has been extracted into OrderRepository. Having a separate object is beneficial in many ways. For instance, it simplifies testing as it can be mocked up or faked.
• Instances of Order and Item are no longer responsible for saving or updating themselves. The only way to do it is to use domain specific methods.
• Low-level methods (such as update_attributes!) are no longer exposed.
• There are no has_many associations. The result of it is an enforced aggregate boundary.
• Having validations separated enables better composability and simplifies testing.

Wrapping Up

The suggested approach is fairly simple, but provides some real value when it comes to expressing complex domains. The approach plays really well with legacy applications. Nothing has to be rewritten or redesigned from scratch. Just start using your existing Active Record models as data classes when building new functionality.

GitHub

An implementation of the described approach is available on Github: https://github.com/nulogy/edr