Rails Service Objects: A Comprehensive Guide
2018-05-07
4157 words
20 mins read
This post was written by Amin Shah Gilani, Ruby Developer for Toptal.
Ruby on Rails ships with everything you need to prototype your application quickly, but when your codebase starts growing, you’ll run into scenarios where the conventional Fat Model, Skinny Controller mantra breaks. When your business logic can’t fit into either a model or a controller, that’s when service objects come in and let us separate every business action into its own Ruby object.
In this article, I’ll explain when a service object is required; how to go about writing clean service objects and grouping them together for contributor sanity; the strict rules I impose on my service objects to tie them directly to my business logic; and how not to turn your service objects into a dumping ground for all the code you don’t know what to do with.
Why Do I Need Service Objects?
Try this: What do you do when your application needs to tweet the text from
<td>
<div class="text codecolorer">
params[:message]
</div>
</td>
</tr>
|
1
|
?
If you’ve been using vanilla Rails so far, then you’ve probably done something like this:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">create</span></span>
send_tweet(params[<span class="hljs-symbol">:message</span>])
<span class="hljs-keyword">end</span>
private
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">send_tweet</span><span class="hljs-params">(tweet)</span></span>
client = Twitter::REST::Client.new <span class="hljs-keyword">do</span> <span class="hljs-params">|config|</span>
config.consumer_key = ENV[<span class="hljs-string">'TWITTER_CONSUMER_KEY'</span>]
config.consumer_secret = ENV[<span class="hljs-string">'TWITTER_CONSUMER_SECRET'</span>]
config.access_token = ENV[<span class="hljs-string">'TWITTER_ACCESS_TOKEN'</span>]
config.access_token_secret = ENV[<span class="hljs-string">'TWITTER_ACCESS_SECRET'</span>]
<span class="hljs-keyword">end</span>
client.update(tweet)
<span class="hljs-keyword">end</span>
<span class="hljs-keyword">end</span>
The problem here is that you’ve added at least ten lines to your controller, but they don’t really belong there. Also, what if you wanted to use the same functionality in another controller? Do you move this to a concern? Wait, but this code doesn’t really belong in controllers at all. Why can’t the Twitter API just come with a single prepared object for me to call?
The first time I did this, I felt like I’d done something dirty. My, previously, beautifully lean Rails controllers had started getting fat and I didn’t know what to do. Eventually, I fixed my controller with a service object.
Before you start reading this article, let’s pretend:
- This application handles a Twitter account.
- The Rails Way means “the conventional Ruby on Rails way of doing things” and the book doesn’t exist.
- I’m a Rails expert… which I’m told every day that I am, but I have trouble believing it, so let’s just pretend that I really am one.
What Are Service Objects?
Service objects are Plain Old Ruby Objects (PORO) that are designed to execute one single action in your domain logic and do it well. Consider the example above: Our method already has the logic to do one single thing, and that is to create a tweet. What if this logic was encapsulated within a single Ruby class that we can instantiate and call a method to? Something like:
2
3
4
5
6
7
tweet_creator.send_tweet
<span class="hljs-comment"># Later on in the article, we'll add syntactic sugar and shorten the above to:</span>
TweetCreator.call(params[<span class="hljs-symbol">:message</span>])
This is pretty much it; our
<td>
<div class="text codecolorer">
TweetCreator
</div>
</td>
</tr>
|
1
|
service object, once created, can be called from anywhere, and it would do this one thing very well.
Creating a Service Object
First let’s create a new
<td>
<div class="text codecolorer">
TweetCreator
</div>
</td>
</tr>
|
1
|
in a new folder called
<td>
<div class="text codecolorer">
app/services
</div>
</td>
</tr>
|
1
|
:
And let’s just dump all our logic inside a new Ruby class:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">TweetCreator</span></span>
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">initialize</span><span class="hljs-params">(message)</span></span>
@message = message
<span class="hljs-keyword">end</span>
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">send_tweet</span></span>
client = Twitter::REST::Client.new <span class="hljs-keyword">do</span> <span class="hljs-params">|config|</span>
config.consumer_key = ENV[<span class="hljs-string">'TWITTER_CONSUMER_KEY'</span>]
config.consumer_secret = ENV[<span class="hljs-string">'TWITTER_CONSUMER_SECRET'</span>]
config.access_token = ENV[<span class="hljs-string">'TWITTER_ACCESS_TOKEN'</span>]
config.access_token_secret = ENV[<span class="hljs-string">'TWITTER_ACCESS_SECRET'</span>]
<span class="hljs-keyword">end</span>
client.update(@message)
<span class="hljs-keyword">end</span>
<span class="hljs-keyword">end</span>
Then you can call
<td>
<div class="text codecolorer">
TweetCreator.new(params[:message]).send_tweet
</div>
</td>
</tr>
|
1
|
anywhere in your app, and it will work. Rails will load this object magically because it autoloads everything under
<td>
<div class="text codecolorer">
app/
</div>
</td>
</tr>
|
1
|
. Verify this by running:
2
3
4
5
6
Running via Spring preloader <span class="hljs-keyword">in</span> process <span class="hljs-number">12417</span>
Loading development environment (Rails <span class="hljs-number">5.1</span>.<span class="hljs-number">5</span>)
> puts ActiveSupport::Dependencies.autoload_paths
...
/Users/gilani/Sandbox/nazdeeq/app/services
Want to know more about how
<td>
<div class="text codecolorer">
autoload
</div>
</td>
</tr>
|
1
|
works? Read the Autoloading and Reloading Constants Guide.
Adding Syntactic Sugar to Make Rails Service Objects Suck Less
Look, this feels great in theory, but
<td>
<div class="text codecolorer">
TweetCreator.new(params[:message]).send_tweet
</div>
</td>
</tr>
|
1
|
is just a mouthful. It’s far too verbose with redundant words… much like HTML (ba-dum tiss!). In all seriousness, though, why do people use HTML when HAML is around? Or even Slim. I guess that’s another article for another time. Back to the task at hand:
<td>
<div class="text codecolorer">
TweetCreator
</div>
</td>
</tr>
|
1
|
is a nice short class name, but the extra cruft around instantiating the object and calling the method is just too long! If only there were precedence in Ruby for calling something and having it execute itself immediately with the given parameters… oh wait, there is! It’s
<td>
<div class="text codecolorer">
Proc#call
</div>
</td>
</tr>
|
1
|
.
**
<td> <div class="text codecolorer"> Proc*call </div> </td> </tr>
invokes the block, setting the block’s parameters to the values in params using something close to method calling semantics. It returns the value of the last expression evaluated in the block.
<td>
<div class="text codecolorer">
a_proc = Proc.new {<span class="hljs-params">|scalar, *values|</span> values.map {<span class="hljs-params">|value|</span> value*scalar } }<br />
a_proc.call(<span class="hljs-number">9</span>, <span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>) <span class="hljs-comment">#=> [9, 18, 27]</span><br />
a_proc[<span class="hljs-number">9</span>, <span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>] <span class="hljs-comment">#=> [9, 18, 27]</span><br />
a_proc.(<span class="hljs-number">9</span>, <span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>) <span class="hljs-comment">#=> [9, 18, 27]</span><br />
a_proc.<span class="hljs-keyword">yield</span>(<span class="hljs-number">9</span>, <span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>) <span class="hljs-comment">#=> [9, 18, 27]</span>
</div>
</td>
</tr>
|
1
2 3 4 5 |
If this confuses you, let me explain. A
<td>
<div class="text codecolorer">
proc
</div>
</td>
</tr>
|
1
|
can be
<td>
<div class="text codecolorer">
call
</div>
</td>
</tr>
|
1
|
-ed to execute itself with the given parameters. Which means, that if
<td>
<div class="text codecolorer">
TweetCreator
</div>
</td>
</tr>
|
1
|
were a
<td>
<div class="text codecolorer">
proc
</div>
</td>
</tr>
|
1
|
, we could call it with
<td>
<div class="text codecolorer">
TweetCreator.call(message)
</div>
</td>
</tr>
|
1
|
and the result would be equivalent to
<td>
<div class="text codecolorer">
TweetCreator.new(params[:message]).call
</div>
</td>
</tr>
|
1
|
, which looks quite similar to our unwieldy old
<td>
<div class="text codecolorer">
TweetCreator.new(params[:message]).send_tweet
</div>
</td>
</tr>
|
1
|
.
So let’s make our service object behave more like a
<td>
<div class="text codecolorer">
proc
</div>
</td>
</tr>
|
1
|
!
First, because we probably want to reuse this behavior across all our service objects, let’s borrow from the Rails Way and create a class called
<td>
<div class="text codecolorer">
ApplicationService
</div>
</td>
</tr>
|
1
|
:
<td> <div class="text codecolorer"> <span class="hljs-comment"># app/services/application_service.rb</span><br /> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">ApplicationService</span></span><br /> <span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">self</span>.<span class="hljs-title">call</span><span class="hljs-params">(*args, &block)</span></span><br /> new(*args, &block).call<br /> <span class="hljs-keyword">end</span><br /> <span class="hljs-keyword">end</span> </div> </td> </tr>
2
3
4
5
6
Did you see what I did there? I added a class method called
<td> <div class="text codecolorer"> call </div> </td> </tr>
that creates a new instance of the class with the arguments or block you pass to it, and calls
<td> <div class="text codecolorer"> call </div> </td> </tr>
on the instance. Exactly what we we wanted! The last thing to do is to rename the method from our
<td> <div class="text codecolorer"> TweetCreator </div> </td> </tr>
class to
<td> <div class="text codecolorer"> call </div> </td> </tr>
, and have the class inherit from
<td> <div class="text codecolorer"> ApplicationService </div> </td> </tr>
:
<td>
<div class="text codecolorer">
<span class="hljs-comment"># app/services/tweet_creator.rb</span><br />
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">TweetCreator</span> < ApplicationService</span><br />
<span class="hljs-keyword">attr_reader</span> <span class="hljs-symbol">:message</span><br />
<br />
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">initialize</span><span class="hljs-params">(message)</span></span><br />
@message = message<br />
<span class="hljs-keyword">end</span><br />
<br />
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">call</span></span><br />
client = Twitter::REST::Client.new <span class="hljs-keyword">do</span> <span class="hljs-params">|config|</span><br />
config.consumer_key = ENV[<span class="hljs-string">'TWITTER_CONSUMER_KEY'</span>]<br />
config.consumer_secret = ENV[<span class="hljs-string">'TWITTER_CONSUMER_SECRET'</span>]<br />
config.access_token = ENV[<span class="hljs-string">'TWITTER_ACCESS_TOKEN'</span>]<br />
config.access_token_secret = ENV[<span class="hljs-string">'TWITTER_ACCESS_SECRET'</span>]<br />
<span class="hljs-keyword">end</span><br />
client.update(@message)<br />
<span class="hljs-keyword">end</span><br />
<span class="hljs-keyword">end</span>
</div>
</td>
</tr>
|
1
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
And finally, let’s wrap this up by calling our service object in the controller:
<td>
<div class="text codecolorer">
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">TweetController</span> < ApplicationController</span><br />
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">create</span></span><br />
TweetCreator.call(params[<span class="hljs-symbol">:message</span>])<br />
<span class="hljs-keyword">end</span><br />
<span class="hljs-keyword">end</span>
</div>
</td>
</tr>
|
1
2 3 4 5 |
