Skip to content

Getting started

Conventions

  • All services are subclasses of Servactory::Base and are located in the app/services directory. It is common practice to create and inherit from ApplicationService::Base, which is a subclass of Servactory::Base.
  • Name services by what they do, not by what they accept. Use verbs in names. For example, UsersService::Create instead of UsersService::Creation.

Version support

Ruby/Rails7.27.17.06.16.05.25.15.0
3.3
3.2
3.1
3.0

Installation

Add this to Gemfile:

ruby
gem "servactory"

And execute:

shell
bundle install

Preparation

As a first step, it is recommended to prepare the base class for further inheritance.

Automatically Since 2.5.0

To quickly prepare your environment for work, you can use the rake task:

shell
bundle exec rails g servactory:install

This will create all the necessary files.

Manually

ApplicationService::Exceptions

ruby
module ApplicationService
  module Exceptions
    class Input < Servactory::Exceptions::Input; end
    class Output < Servactory::Exceptions::Output; end
    class Internal < Servactory::Exceptions::Internal; end

    class Failure < Servactory::Exceptions::Failure; end
  end
end

ApplicationService::Result Since 2.5.0

ruby
module ApplicationService
  class Result < Servactory::Result; end
end

ApplicationService::Base

ruby
module ApplicationService
  class Base < Servactory::Base
    configuration do
      input_exception_class ApplicationService::Exceptions::Input
      internal_exception_class ApplicationService::Exceptions::Internal
      output_exception_class ApplicationService::Exceptions::Output

      failure_class ApplicationService::Exceptions::Failure

      result_class ApplicationService::Result
    end
  end
end

First service

Now you can create your first service. To do this, you can use the rake task:

shell
bundle exec rails g servactory:service users_service/create first_name middle_name last_name

You can also immediately prepare a spec file for testing the service:

shell
bundle exec rails g servactory:rspec users_service/create first_name middle_name last_name