Are service objects enough?

There have been a lot of buzz around service objects in Ruby community. It started some time ago and new articles about them popped up like mushrooms. I still think about myself as a “developer in progress” and I think it’s a good approach for all of us. We should always keep learning new stuff. For me, the so-called service objects were like a milestone. A lot of things started to look simpler with them. So how does the perfect implementation of service objects looks to me?

The perfect world

I assume that we all know what service objects are. If you are not familiar with them there is a ton of great articles about them. You can check here or here how to use them with Rails applications.

So we all know the main concepts: it should be a small class that does just one thing — some operation. It should be easy to test and not coupled your Rails application. But the problem is there are still a lot of questions about implementation details when using them in big projects.

What if we need to add some logic to existing service object? Should we create another service object and run it after the first one? Or should we process it within the initial one? What should we do if we want to get some data from service object after it does its job? Should we create some reader / method or return needed value from the main method? Should service objects even return something?

As you can see all these things can lead to long discussions in your pull requests. It’s good to think about these problems at the beginning.

Let’s assume we are implementing some registration functionality. We need to create a user and then send a welcome mail with some unique token inside.

So how can we implement it? There are basically 3 things we need to cover:

  • Creating a new user record in the database
  • Generating some unique token for created user
  • Sending a welcome mail with the token inside

It’s worth splitting those tasks to separate and small service objects. But in reality, we are still talking about one action for the end user — registration. That’s why it makes sense to introduce another layer of abstraction in our codebase — the commands. They are like glue to our service objects. The idea of it is: We call a command object from our controller and it can call many service objects.

The return value

For command objects, I really like the approach of broadcasting events, like in wisper gem. It solves one of the most important problems for me — the return value. Many times have I seen inconsistency in this area, for example:

User::NotifyAdmins.call(params)

No return value. The service object is just responsible for sending email or message on Slack.


user = User::Create.call(params)
...
if User::Contracts.call(user)
...

Returning some data from the main service object method. It can be some record or boolean value. We can just assume what it really is.


user_creation = User::Create.new(params)
user_creation.call
user = user_creation.created_user

Explicitly returns a user with separate method / reader. All the examples above are just inconsistent. It can be confusing, harder to understand for new developers and even more difficult to test.


With the wisper gem we don’t return any value from calling the command itself. We just add listeners in controllers for every possible event we implement. Those events can include needed arguments when we need to get some data. Seems confusing? Let’s look at the example:

class User::Register
include Wisper::Publisher

def call(email)
return broadcast(:invalid) if email.blank?
user = User.create!(email: email)
broadcast(:ok, user.id)
end
end

...
controller action
...

def create
register_user = User::Register.new

register_user.on(:invalid) do
@user = User.new
flash.now[:alert] = "Email address is missing"
render :new
end

register_user.on(:ok) { |user_id| redirect_to user_path(user_id) }

register_user.call(params[:email])
end

That’s the first step of our implementation of the command object. I would put this class in the app/commands/user folder and move on to adding further things.

Using service objects

So what about the so-called service objects? In my approach, they are still useful for doing one small thing and returning some value. In our example, they could generate a unique token. A small class like:

class User::GenerateToken
def self.call(user)
new(user).call
end

def initialize(user)
@user = user
end

def call
(generate and return token)
end
end

is really easy to test in isolation and can be easily added to our command object. So the final implementation would look like:

class User::Register
include Wisper::Publisher

def call(email)
return broadcast(:invalid) if email.blank?

user = User.create!(email: email)
token = User::GenerateToken.call(user)
UserMailer.welcome(user.id, token).deliver_later

broadcast(:ok, user.id)
end
end

This allows us to extend or change our class in the future with little time. We could also broadcast more events with some other validation.

The way to call commands

There is still one thing we could improve in my opinion. I’m not sold on the way we call command objects in our controllers. I suggest creating a base module for our commands:

module BaseCommand
extend ActiveSupport::Concern

included do
include Wisper::Publisher

def self.call(*args)
new(*args).tap { |obj| yield obj }.call
end
end
end

Now change the User::Register class to:

class User::Register
include BaseCommand

def initialize(email)
@email = email
end

def call
return broadcast(:invalid) if email.blank?

user = User.create!(email: email)
token = User::GenerateToken.call(user)
UserMailer.welcome(user.id, token).deliver_later

broadcast(:ok, user.id)
end

private

attr_reader :email
end

This way we don’t need to instantiate command object and can use it in controllers like:

def create
User::Register.call(params[:email]) do |register_user|
register_user.on(:invalid) do
@user = User.new
flash.now[:alert] = "Email address is missing"
render :new
end

register_user.on(:ok) { |user_id| redirect_to user_path(user_id) }
end
end

I think it looks awesome!

It’s also worth adding that there is a wisper-rspec gem which helps with testing when using Rspec. You can test if command broadcasts proper event or stub them in requests specs.

Wrapping up

If you want a clean architecture in your app, consider adding the command objects layer. There are places where you need to perform few operations one after another. If you could group them into one, logical action, you got a place for command. They should call service objects or perform some simple logic by itself. I also recommend you to try the wisper library. It can clean your controllers and add some guidelines for other developers. It should help with keeping your code clean, easy to test and maintainable in the future.


Originally published at blog.ragnarson.com on October 19, 2016.