A Case for Use Cases

If you cut your teeth on Ruby on Rails, at some point you've probably shuffled domain logic from views to controllers to models to POROs in pursuit of Separation of Concerns.

At Envato, we recently introduced the Use Case pattern as a contextual, well-defined interface between your Rails controllers and your domain entities. This presentation walks through a real example and explains how these nifty little classes can reveal your user stories while also encapsulating complex business logic.

Presented at RubyConf AU 2015.

Accompanying blog post can be found here: http://webuild.envato.com/blog/a-case-for-use-cases/

Transcript

1. A Case for Use Cases
2. Use Cases VS The State (of Rails applications)
3. Shevaun Coker @shevauncoker Prosecutor
6. Shevaun Coker Court Reporter
7. Use Case Defendant
8. Charges
9. Reducing coupling between the Rails framework and business domain Charges
10. Increasing visibility of features within the codebase Charges
11. Encapsulating complex business logic Charges
12. The following presentation contains explicit code scenes. Viewer discretion is advised. Warning!
13. Opening Statement
16. Sole Requirement: A buyer can purchase a photo
17. Photo Buyer Purchase
18. $ rails g model Buyer
19. $ rails g model Buyer class Buyer < ActiveRecord::Base end
20. $ rails g model Photo
21. class Photo < ActiveRecord::Base end $ rails g model Photo
22. $ rails g model Purchase
23. $ rails g model Purchase class Purchase < ActiveRecord::Base belongs_to :photo belongs_to :buyer end
24. $ rails g controller Purchases
25. $ rails g controller Purchases class PurchasesController < ApplicationController def create Purchase.create!(buyer: buyer, photo: photo) redirect_to purchase_completed_path end end
26. $ rails g controller Purchases class PurchasesController < ApplicationController def create Purchase.create!(buyer: buyer, photo: photo) redirect_to purchase_completed_path end end
27. class PurchasesController < ApplicationController def create Purchase.create!(buyer, photo) redirect_to purchase_completed_path end end $ rails g controller Purchases
28. class PurchasesController < ApplicationController def create Purchase.create!(buyer, photo) redirect_to purchase_completed_path end end $ rails g controller Purchases
30. SOME TIME LATER…
31. Sole Requirement: A buyer can purchase a photo s A buyer receives a purchase invoice Record the sales count of each photo A buyer can review a purchased photo Updated
32. class PurchasesController def create purchase = Purchase.create!(buyer, photo) BuyerMail.invoice.deliver(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) redirect_to purchase_completed_path end end
33. class PurchasesController def create purchase = Purchase.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) redirect_to purchase_completed_path end end
34. class PurchasesController def create purchase = Purchase.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) redirect_to purchase_completed_path end end
35. class PurchasesController def create purchase = Purchase.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) redirect_to purchase_completed_path end end
38. class Purchase < ActiveRecord::Base def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
39. class Purchase < ActiveRecord::Base def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
40. class PurchasesController def create purchase = Purchase.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) redirect_to purchase_completed_path end end
41. class PurchasesController def create purchase = Purchase.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) redirect_to purchase_completed_path end end
42. class Purchase < ActiveRecord::Base def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
43. class Purchase < ActiveRecord::Base def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
44. class PurchasesController def create Purchase.create_for_buyer!(buyer, photo) redirect_to purchase_completed_path end end
45. class PurchasesController def create Purchase.create_for_buyer!(buyer, photo) redirect_to purchase_completed_path end end
47. http://wall.alphacoders.com/big.php?i=117571
48. class Purchase < ActiveRecord::Base def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
49. class Purchase < ActiveRecord::Base def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
50. class Purchase < ActiveRecord::Base; end def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
51. class Purchase < ActiveRecord::Base; end def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end > Purchase.instance_methods.size - Object.instance_methods.size => 214
52. class Purchase < ActiveRecord::Base def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
53. class Purchase < ActiveRecord::Base def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
54. class Purchase < ActiveRecord::Base def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
55. class Purchase < ActiveRecord::Base def self.create_for_buyer(buyer, photo) purchase = self.create!(buyer, photo) BuyerMailer.send_invoice(buyer, purchase) photo.increment_sales_count buyer.enable_review_of(photo) end end
56. Too many responsibilities
57. Harder to change
58. More error & conflict prone
59. Huge class files
61. http://techmaster.vn/2014/07/blogging-rails-02-mvc-trong-rails/
62. Taking the Stand
63. What is a Use Case?
65. A use case is a written description of how users will perform tasks on your website. usability.gov
66. It outlines, from a user's point of view, a system's behaviour as it responds to a request. usability.gov
67. Each use case is represented as a sequence of simple steps, beginning with a user's goal and ending when that goal is fulfilled. usability.gov
68. http://commons.wikimedia.org/wiki/File:CCTS_CI_Use_Case.png
69. Reflect the architecture in the code
70. Reflect the use cases in the code
71. Examining the Witness
72. How did we implement use cases at Envato?
73. “an action a user of a system takes to achieve a goal”
74. * PurchasePhoto * ConfirmEmail * ResetPassword * VerifySignIn
75. $ls app/use_cases purchase_photo.rb confirm_email.rb reset_password.rb verify_sign_in.rb
76. module UseCase extend ActiveSupport::Concern module ClassMethods def perform(*args) new(*args).tap { |use_case| use_case.perform } end end def perform raise NotImplementedError end end
77. module UseCase extend ActiveSupport::Concern module ClassMethods def perform(*args) new(*args).tap { |use_case| use_case.perform } end end def perform raise NotImplementedError end end
78. module UseCase extend ActiveSupport::Concern module ClassMethods def perform(*args) new(*args).tap { |use_case| use_case.perform } end end def perform raise NotImplementedError end end
79. module UseCase extend ActiveSupport::Concern module ClassMethods def perform(*args) new(*args).tap { |use_case| use_case.perform } end end def perform raise NotImplementedError end end
80. module UseCase extend ActiveSupport::Concern module ClassMethods def perform(*args) new(*args).tap { |use_case| use_case.perform } end end def perform raise NotImplementedError end end
81. class PurchasePhoto include UseCase def initialize(buyer, photo) @buyer = buyer @photo = photo end def perform create_purchase send_invoice increment_sales_count allow_buyer_to_review_photo end end
82. class PurchasePhoto include UseCase def initialize(buyer, photo) @buyer = buyer @photo = photo end def perform create_purchase send_invoice increment_sales_count allow_buyer_to_review_photo end end
83. class PurchasePhoto include UseCase def initialize(buyer, photo) @buyer = buyer @photo = photo end def perform create_purchase send_invoice increment_sales_count allow_buyer_to_review_photo end end
84. class PurchasePhoto include UseCase def initialize(buyer, photo) @buyer = buyer @photo = photo end def perform create_purchase send_invoice increment_sales_count allow_buyer_to_review_photo end end
85. class PurchasePhoto include UseCase def initialize(buyer, photo) @buyer = buyer @photo = photo end def perform create_purchase send_invoice increment_sales_count allow_buyer_to_review_photo end end
86. class PurchasePhoto include UseCase def initialize(buyer, photo) @buyer = buyer @photo = photo end def perform create_purchase send_invoice increment_sales_count allow_buyer_to_review_photo end end
87. private def create_purchase @purchase = Purchase.create!(buyer, photo) end def send_invoice Buyer::InvoiceMailer.enqueue(purchase) end def increment_sales_count Photo::SalesCount.increment(photo) end def allow_buyer_to_review_photo Photo::ReviewPermissions.add_buyer(buyer, photo) end
88. class PurchasePhoto include UseCase include ActiveModel::Validations def success? errors.none? end end
89. class PurchasesController def create use_case = PurchasePhoto.perform if use_case.success? redirect_to purchase_completed_path else redirect_to purchase_failed_path end end end
90. class PurchasesController def create use_case = PurchasePhoto.perform if use_case.success? redirect_to purchase_completed_path else redirect_to purchase_failed_path end end end
91. class PurchasesController def create use_case = PurchasePhoto.perform if use_case.success? redirect_to purchase_completed_path else redirect_to purchase_failed_path end end end
92. class PurchasesController def create use_case = PurchasePhoto.perform if use_case.success? redirect_to purchase_completed_path else redirect_to purchase_failed_path end end end
93. Hearing from the Defence
94. Lessons Learned
95. Command Query Separation Bertrand Meyer, Object Oriented Software Construction Lesson 1
96. Command: has side effects, no return value
97. Query: idempotent, returns a value
98. “We conflate commands and queries at our peril” Sandi Metz, Magic Tricks of Testing 2013
99. A great fit for Integration Tests Lesson 2
100. acceptance integration unit Test Coverage
101. RSpec.describe PurchasePhoto do describe “#perform” do subject(:perform) { PurchasePhoto.perform(buyer, photo) } it “creates a purchase record” do expect { perform }.to change { Purchase.count }.by(1) end it “sends an invoice” do perform expect(Mailer.deliveries.last). to have_attributes(subject: “Purchase Invoice”) end end end
102. RSpec.describe PurchasePhoto do describe “#perform” do subject(:perform) { PurchasePhoto.perform(buyer, photo) } it “creates a purchase record” do expect { perform }.to change { Purchase.count }.by(1) end it “sends an invoice” do perform expect(Mailer.deliveries.last). to have_attributes(subject: “Purchase Invoice”) end end end
103. RSpec.describe PurchasePhoto do describe “#perform” do subject(:perform) { PurchasePhoto.perform(buyer, photo) } it “creates a purchase record” do expect { perform }.to change { Purchase.count }.by(1) end it “sends an invoice” do perform expect(Mailer.deliveries.last). to have_attributes(subject: “Purchase Invoice”) end end end
104. RSpec.describe PurchasePhoto do describe “#perform” do subject(:perform) { PurchasePhoto.perform(buyer, photo) } it “creates a purchase record” do expect { perform }.to change { Purchase.count }.by(1) end it “sends an invoice” do perform expect(Mailer.deliveries.last). to have_attributes(subject: “Purchase Invoice”) end end end
105. Don’t put low level logic in your UseCase Lesson 3
108. private def create_purchase @purchase = Purchase.create!(buyer, photo) end def send_invoice Buyer::InvoiceMailer.enqueue(purchase) end def increment_sales_count Photo::SalesCount.increment(photo) end def allow_buyer_to_review_photo Photo::ReviewPermissions.add_buyer(buyer, photo) end
109. Don’t make your UseCases generic Lesson 4
110. http://veryfunnypics.eu/2013/07/19/canadian-protest-signs/
111. Presenting the Evidence
112. A Consistent Interface Provides
113. PurchasePhoto.perform(buyer, photo) class PurchasePhoto include UseCase #... end
114. PurchasePhoto.perform(buyer, photo) class PurchasePhoto include UseCase #... end
115. Self Documenting & Readable Code Provides
116. class PurchasePhoto include UseCase def perform create_purchase send_invoice increment_sales_count allow_buyer_to_review_photo end end
117. private def create_purchase @purchase = Purchase.create!(buyer, photo) end def send_invoice Buyer::InvoiceMailer.enqueue(purchase) end def increment_sales_count Photo::SalesCount.increment(photo) end def allow_buyer_to_review_photo Photo::ReviewPermissions.add_buyer(buyer, photo) end
118. Context & Encapsulation Provides
120. class PurchasePhoto def initialize(buyer, photo) @buyer = buyer @photo = photo end def perform # steps end end
121. Extensibility Provides
122. private def create_purchase @purchase = Purchase.create!(buyer, photo) end def send_invoice Buyer::InvoiceMailer.enqueue(purchase) end # ... def send_purchase_confirmation Purchase::ConfirmationMailer.enqueue(purchase) end def allow_buyer_to_review_photo
123. private def create_purchase @purchase = Purchase.create!(buyer, photo) end def send_invoice Buyer::InvoiceMailer.enqueue(purchase) end # ... def send_confirmation_email Purchase::ConfirmationMailer.enqueue(purchase) end def allow_buyer_to_review_photo
124. class PurchasePhoto include UseCase def perform create_purchase send_invoice increment_sales_count allow_buyer_to_review_photo end end
125. class PurchasePhoto include UseCase def perform create_purchase send_invoice increment_sales_count allow_buyer_to_review_photo send_confirmation_email end end
126. Decoupling from your framework Provides
128. A codebase that reveals its features Provides
129. $ls app/use_cases purchase_photo.rb confirm_email.rb reset_password.rb verify_sign_in.rb
130. Objection!
131. http://i.imgur.com/aXTps4g.jpg
132. Use Case is a perfectly cromulent name
133. Illustration by Leslie Herman
134. cjohansen/use_case cypriss/mutations stevehodgkiss/interaction collectiveidea/interactor https://github.com/
135. cjohansen/use_case cypriss/mutations stevehodgkiss/interaction collectiveidea/interactor https://github.com/
136. cjohansen/use_case cypriss/mutations stevehodgkiss/interaction collectiveidea/interactor https://github.com/
137. cjohansen/use_case cypriss/mutations stevehodgkiss/interaction collectiveidea/interactor https://github.com/
138. cjohansen/use_case cypriss/mutations stevehodgkiss/interaction collectiveidea/interactor https://github.com/
139. Closing Statement
140. Reduces Coupling Increases feature visibility Encapsulates complex logic
141. Reduces Coupling Increases feature visibility Encapsulates complex logic GUILTY
142. CASE CLOSED
143. webuild.envato.com/blog/a-case-for-use-cases