Blog

Saturday, December 24, 2011

Your Rails Application is Missing a Domain Controller

The mantra of Skinny Controller, Fat Model reminds us to keep our business logic in our models, not in Rails Action Controllers. We know Action Controllers, sub-classes of ActionController::Base, are only responsible for delegating service requests to the domain layer. These models, which encapsulate this business logic, forming the domain layer, represent entities such as a person, place, event or thing. They are often, but not always, mapped directly to database tables through the inheritance of ActiveRecord::Base. When we develop our domain layer for our complex Rails application, purely with models representing entities, we encounter two problems:

Incoherent domain API

When Action Controllers interact with model entities directly, the API to the domain layer becomes clouded. It is unclear what services the domain layer offers and how the UI should request those services. Rail’s ActiveRecord exasperates the issue, for example, there are several ways to create and update model entities and their associations.

Bloated domain models

Business logic that is workflow-oriented involving multiple entities is assigned to a single entity, bloating it’s responsibilities. It becomes difficult to differentiate the entities in the domainrepresenting what the system is, from the use cases or workflow representing what the system does1.

The solution is a Domain Controller. A Domain Controller is responsible for co-ordinating service requests from your Rails Action Controllers. A Domain Controller can come in two flavours, a facade or a use case.

A clarification on terminology: Throughout this blog post I will refer to the typical Rails model as a Model Entity, meaning a model that represents a person, place, event or thing.

Facade Controller

A Facade Controller represents the overall system that encapsulates the domain layer. For example a Catalog object can act as facade for the domain layer containing taxonomies, taxons, product groups, products and variants.

Without the Facade Controller, our service requests to the domain typically look like this:

Product.active
Taxon.active.find(1)
Product.create(:name => 'Ruby Meta-Programming')

With a Facade Controller instance, in this case, a catalog object, service requests appear as the following, delegating to the appropriate Model Entities:

catalog.fetch_products
catalog.fetch_taxon(1)
catalog.create_product(:name => 'Ruby Meta-Programming')

The Facade Controller provides a clear, explicit interface into the catalog domain layer that a programmer can grok within seconds.

Use Case Controller

A Use Case Controller is useful for more complex workflows. They are also helpful when a Facade becomes bloated and you wish to split the incoming service requests across multiple Domain Controllers. It’s important to note, you can use more than one Domain Controller for your application.

Let’s look at an example. The code below represents the processing of a Payroll2. Often this type of workflow logic gets placed in a Model Entity that it doesn’t belong to or worst, left in a Rails Action Controller.

date = Date.today
employees = Employee.active
employees.each do |e|
  if e.pay_date?(date)
    pc = PayCheck.new(e.calculate_pay(date))
    e.send_pay(pc)
  end
end

So what object is responsible for this workflow logic? We know a Rails Action Controller isn’t a candidate. Its responsibility is to handle HTTP requests and delegate to the domain layer. Neither the models Employee or PayCheck are valid candidates. They represents the entities in our domain layer. Therefore we, require a new object PayDayService to encapsulate the logic, a Use Case Controller.

class PayDayService
    def initialize(date=Date.now)
      @date = date
    end

    def call
      Employee.active.each do |e|
        if e.pay_date?(@date)
          pc = PayCheck.new(e.calculate_pay(@date))
          e.send_pay(pc)
        end
      end
    end
  end

The benefit of this approach is that we have encapsulated this workflow logic without bloating existing Model Entities and allows the reuse of this logic in different contexts.

Domain Controllers in a Rails Application

When an application has multiple Domain Controllers I place them in a dedicated directory under app called services to keep them separate from the Model entities in app/models. This helps communicate that Rails Action Controllers should delegate to the Domain Controllers, not directly to Model Entities. The Domain Controllers and Model Entities together, represent the domain layer of the system. I have also discussed extracting the entire domain layer from the Rails framework, but that’s another discussion. Let’s keep this blog post civil for now!

I hope the Domain Controller pattern provides you with another tool for modelling your domain, reduces the coupling with the UI, and provides a clean API to your application logic.

Further Reading

If you are interested in learning more about Domain Controllers and Services, check out the following resources:

  • Applying UML and Patterns by Craig Larman. Craig includes the Controller pattern as one of the General Responsibility Assignment Software Patterns or Principles (Grasp).
  • Architecture the Lost Years a presentation by Robert Martin discusses modelling your application using Interactors and Entities. Interactors_ (which I have used the name Domain Controller) contain application specific logic, and Entities (which I have use the term Model Entities) contains application independent logic. Martin choses to use the term Interactors over Controllers to avoid confusing with Model-View-Controller (MVC). I prefer to use Domain Controller or Service to differentiate from Rails Action Controllers as I just can’t get my head around the term Interactors.
  • Object-Oriented Software Engineering—A Use Case Driven Approach by Ivar Jacobson introduced the concept of interface, entity (Model Entity) and control (Domain Controller) objects over two decades ago. Robert Martin often refers to Ivar Jacobson when discussing application architecture.
  • Patterns of Enterprise Application Architecture by Martin Flower discusses the concept of a “Service Layer” to give the domain layer an explicit API.
  • Domain Driven Design by Eric Evans. Evans discusses the concept of Services for when “some concepts from the domain aren’t natural to model as objects”.

Footnotes:

  1. “What-the-system-is” and “What-the-system-does” terminology is from the book Lean Architecture by James O. Coplien and Gertrud Bjørnvig.
  2. Logic based on the Payroll case study in Robert Martin’s Agile Software Development.

Wednesday, December 21, 2011

An Example using RSpec double, mock, and stub

This is a follow-up post for RSpec double, mock, and stub from earlier this year. A reader asked for an example code to illustrate the various double aliases in RSpec.

For this example we will spec a Transfer class that encapsulates the use case of transferring an amount between two accounts, the source account and destination account. The Transfer is the subject of our examples, while the source and destination accounts are the collaborators.

In the spec below, the first example "should decrease source amount by 10", specifies the interaction for the source account, hence the use of the mock to generate the test double. In this example, the destination account is treated as a secondary collaborator, as we are focusing on the role of the source account. Any object can play the role of the source account, as long as it responds to the #decrease method.

In the second example "should increase destination account by 10", the destination account is the primary collaborator. The use of mock to generate the source account communicates this intent.

describe Transfer do
  context "transfer with amount of 10" do
    it "should decrease source account by 10" do
      source_account      = mock('source account')
      destination_account = stub('destination_account').as_null_object
    
      source_account.should_receive('decrease').with(10)
    
      transfer = Transfer.new(source_account, destination_account, 10)
      transfer.call
    end

    it "should increase destination account by 10" do
      source_account      = stub('source account').as_null_object
      destination_account = mock('destination_account')
    
      destination_account.should_receive('increase').with(10)
    
      transfer = Transfer.new(source_account, destination_account, 10)
      transfer.call
    end
  end
end

However, there is some duplication in this spec which can be eliminated by moving the test doubles to let blocks. It's appropriate to use double here to generate the source and destination accounts as both play primary and secondary collaborators in the following examples. Below we stub the methods for each collaborator, then set expectations on those methods for the appropriate examples.

describe Transfer do
  context "transfer with amount of 10" do
    let(:source_account) { double('source account', :decrease => nil) }
    let(:destination_account) { double('destination_account', :increase => nil) }

    it "should decrease source account by 10" do
      source_account.should_receive('decrease').with(10)
    
      transfer = Transfer.new(source_account, destination_account, 10)
      transfer.call
    end

    it "should increase destination account by 10" do
      destination_account.should_receive('increase').with(10)
    
      transfer = Transfer.new(source_account, destination_account, 10)
      transfer.call
    end
  end
end

Update: Radoslav Stankov provides a cleaner refactoring of the spec.

The implementation of the transfer class may look something like this:

class Transfer
  def initialize(source_account, destination_account, amount)
    @source_account      = source_account
    @destination_account = destination_account
    @amount              = amount
  end
  
  def call
    # In a complete implementation, it would make sense to have the following 
    # lines wrapped in a transaction, but I wanted to keep this example simple
    #
    @source_account.decrease(amount)
    @destination_account.increase(amount)
  end
end

It's important to remember that double, mock, and stub all return an instance of RSpec::Mocks::Mock. While the concepts of mocking, (i.e. setting a method expectation), and stubbing are "method-level concepts"[1], the use of mock and stub can communicate which collaborator you are specifying the behaviour for.

[1] For a more complete discussion on this, checkout The RSpec Book.

Recent Launch: Yellow Bird Project Redesign

Earlier this year, I upgraded the Yellow Bird Project, a Spree store, from a forked version pre v0.90.0 to v0.50.x. For for my final project of the year, I upgraded Yellow Bird Project to v0.70.x, along with the implementation of a UI redesign. Jenna Holcombe (Dynamo) did a great job moving the YBP look to a grid-based design, which Daniel Wright (Dynamo) implemented this in Sass/Compass.
Since the redesign initiative included an upgrade to the latest version of Spree, I decided to upgrade the existing site and deploy that to production, before launching the redesign. This allowed me to upgrade our custom extensions to work with 0.70.x and iron out any kinks in the new version. While this was a smoother process than the upgrade earlier this year, it was the first time I had deployed to Heroku's Cedar stack using Rails 3.1 and the asset pipeline. I'm a big advocate of breaking down a project, separating major changes, and getting changes pushed to production early, even it there is a little duplication in work. The separate pushes to production for the upgrade and the redesign reduced the risk of something really going haywire with pushing both of these at once.
The redesign benefited the application from a platform, merchandising, and coding perspectives:
  • Platform: While this initiative did not include a mobile version, the new grid-based design will allow us to cleanly develop a responsive design for mobile platforms in the future using media queries. Replacing hacks like Cufon with more modern technologies like web fonts just makes the UI code cleaner and performance snappier.
  • Merchandising: The store now fully utilizes Spree's powerful Taxonomy and Product Group features. This allows YBP to respond to different marketing initiates such as seasonal events, for example Warm Winter Wear.
  • Code: One of the cool things with this upgrade was the chance to refactor the code base. Shifting from ERB to Haml and plain CSS to Sass/Compass was a definitely a plus, however implementing a data model that capitalized Spree's catalog management was the biggest win. I was able to remove unnecessary extensions which simplified managing the products. YBP's Matthew Stotland is a code-savvy lad and appreciated the clean implementation. It's great to work on a project where the client appreciates the front-end as much as the code that drives it.
You can checkout the new design below, but better yet, visit the Yellow Bird Project and support a great cause.
01 home
Yellowbird Project Product

Please note this blog is no longer maintained. Please visit CivilCode Inc - Custom Software Development.