Spring patterns. Fluent interface

Всем привет.

Я разрабатываю приложения с использованием Java, Spring Boot, Hibernate.

В этой статье я хочу поделиться опытом создания Fluent Interface, но не классического шаблона из GOF, а с использованием Spring.

Классическим примером шаблона Fluent Interface в Java является Stream API. Я покажу, как можно написать нечто подобное, используя Spring.

Пример клиентского кода:

 Participant participant = testEntityFactory.participantBy(RankType.WRITER)             .withName("customName")             .withPost("post_1")             .withPost("post_2")             .withPost("post_3")             .createOne();

Предисловие

Все мы знаем, как легко можно реализовать Chain of Responsibility pattern при помощи Spring:

@Autowired private List<AnyInterface> implementations;

Прогонять через цепочки различные сущности, удобно расширять цепочку при помощи новых имплементаций. А если я хочу использовать не всю цепочку, а только часть, и динамически её менять в клиентском коде? Сейчас покажу.

Показывать я буду на примере модуля, который будет отвечать за создание тестовых сущностей.

1. Подготовка графа сущностей

Для примера необходимо подготовить граф @Entity. Нам понадобятся 3 @Entity: Participant, Rank, Post. Примера кода не будет, обычные @Entity. У Participant один Rank и много Post. Rank может быть 3х видов:

public enum RankType {      READER, WRITER, MODERATOR  }

Значения обычно прописывают в бд скриптами. Для примера это не имеет значения, поэтому ddl скрипты будет генерировать Hibernate, а значения для Rank – RankInitializer, при поднятии Spring контекста:

  @PostConstruct     void init() {         List<Rank> ranks = Arrays.stream(RankType.values())             .map(rankType -> new Rank().setRankType(rankType))             .toList();         rankRepository.saveAll(ranks);     }

2. Классическое создание тестовых сущностей

Для написания тестов я буду использовать SpringBootTest и TestContainers. Создадим класс SpringBootTestApplication, от которого будут наследоваться Spring Boot тесты.

Представим, что нам надо написать тест, для которого надо подготовить сущности. Классическое решение выглядит следующим образом:

class ManualImperativeCreatingExampleTest extends SpringBootTestApplication {      @Test     void test() {         Participant participant = createParticipantManualAndImperative("name", "post", RankType.WRITER);          Assertions.assertEquals(RankType.WRITER, participant.getRank().getRankType());     }      private Participant createParticipantManualAndImperative(String participantName, String postTitle, RankType rankType) {         Rank rank = rankRepository.findByRankType(rankType); // вытащить Rank из бд          Participant participant = new Participant() // создать новый Participant             .setRank(rank)             .setName(participantName);         participantRepository.save(participant); // заперсистить          Post post = new Post() // создать новый Post             .setTitle(postTitle);         postRepository.save(post); // заперсистить          // переженить Participant и Post         participant.getPosts().add(post);         participantRepository.save(participant);          post.setParticipant(participant);         postRepository.save(post);          return participant;     }  }

Скорее всего, изначально за это будет отвечать приватный метод. Потом метод поднимут выше — в класс, от которого наследуются все Spring Boot тесты. Сделают метод protected. Потом рядом появится еще миллион методов, с другими сигнатурами. Потом окажется, что было бы неплохо обернуть создание сущности в транзакцию. Благо это можно легко сделать при помощи TransactionTemplate. В итоге — часть методов с транзакцией, часть без. Класс подобный SpringBootTestApplication превращается в антипаттерн статик утиль – класс на много строк, в котором есть всё, при этом, чтобы что-то найти, не будучи автором, надо потратить много времени, а методы с похожей сигнатурой либо именем метода пытаются пояснить чем они отличаются друг от друга, либо выше написан java-doc, который часто не соответствует текущей реализации метода… Хватит это терпеть 😉

3. Знакомство с TestEntityFactory

Я предпочитаю разносить классы по их ответственности. Поэтому в примере будут отдельные классы для фасада (TestEntityFactory), сборщика колбэков (ParticipantPrototype), колбэка (Callback), бина с реализацией не терминальных операций (ParticipantPrototypeService), бина с реализацией терминальных операций (ParticipantPrototypeFinisher).

 Далее подробнее о каждом из этих классов.

1. TestEntityFactory – фасад, который предоставляет доступ к модулю, является Spring Singleton.

@Service @RequiredArgsConstructor public class TestEntityFactory {      private final ParticipantPrototypeService participantPrototypeService;      public ParticipantPrototype participantBy(RankType rankType) {         return new ParticipantPrototype()             .setRankType(rankType)             .setParticipantPrototypeService(participantPrototypeService);     }  }

В клиентском коде доступ к API модуля будет через TestEntityFactory. Пример:

@Autowired protected TestEntityFactory testEntityFactory;

2. Callback – функциональный интерфейс, в имплементациях которого надо рассказать, как мы хотим модифицировать сущность.

@FunctionalInterface public interface Callback {      void modify(Participant participant);  }

Можно использовать Consumer, но метод apply() в этом контексте не так красноречив, как modify(). Так же можно использовать UnaryOperator<T> (это Function<T, T>) и строить цепочки через andThen(). Но мне больше нравится строить цепочку при помощи List<Callback>.

3. ParticipantPrototype – POJO, который будет собирать List<Callback> и предоставлять доступ к терминальным и не терминальным методам модуля.

@Getter @Setter @Accessors(chain = true) public class ParticipantPrototype {      private RankType rankType;     private ParticipantPrototypeService participantPrototypeService;     private List<Callback> chain = new ArrayList<>();     private int amount;      /**      * terminal operations      */     public Participant createOne() {         this.amount = 1;         return participantPrototypeService.create(this).get(0);     }      public List<Participant> createMany(int amount) {         this.amount = amount;         return participantPrototypeService.create(this);     }      /**      * intermediate operations      */     public ParticipantPrototype with(Callback callback) {         chain.add(callback);         return this;     }      public ParticipantPrototype withName(String participantName) {         chain.add(participant -> participant.setName(participantName));         return this;     }      public ParticipantPrototype withPost(String customTitle) {         chain.add(participant -> participantPrototypeService.addPost(participant, customTitle));         return this;     }  }

Можно использовать spring scope prototype, однако, здесь нужен только 1 сервис, и проще его передать при создании класса. Тем самым разделив ответственность по сбору информации для создания сущности и реализацию методов терминальных и не терминальных операций.

4. ParticipantPrototypeFinisher – Spring Singleton, отвечающий за терминальные операции.  

@Service @RequiredArgsConstructor public class ParticipantPrototypeFinisher {      private final ParticipantRepository participantRepository;     private final RankRepository rankRepository;      @Transactional     public List<Participant> create(ParticipantPrototype prototype) {         List<Participant> result = new ArrayList<>();         for (int i = 0; i < prototype.getAmount(); i++) {             result.add(createOne(prototype));         }         return result;     }      private Participant createOne(ParticipantPrototype prototype) {         /**          * step 1 - create minimum possible @Entity and persist          */         RankType rankType = prototype.getRankType();         Rank rank = rankRepository.findByRankType(rankType);          Participant participant = new Participant()             .setName("defaultName")             .setRank(rank);         participantRepository.save(participant);          /**          * step 2 - add default values          */           /**          * step 3 - modify @Entity by chain          */         List<Callback> chain = prototype.getChain();         chain.forEach(callback -> callback.modify(participant));          return participant;     }  }

 5. ParticipantPrototypeService – Spring Singleton, содержит методы с реализацией не терминальных операций. Добавил пример по созданию Post. Так же через этот класс происходит делегирование терминальных операций в ParticipantPrototypeFinisher.

@Service @RequiredArgsConstructor public class ParticipantPrototypeService {      private final ParticipantPrototypeFinisher participantPrototypeFinisher;     private final ParticipantRepository participantRepository;     private final PostRepository postRepository;      public List<Participant> create(ParticipantPrototype prototype) {         return participantPrototypeFinisher.create(prototype);     }      public void addPost(Participant participant, String postTitle) {         Post post = new Post()             .setTitle(postTitle)             .setParticipant(participant);         postRepository.save(post);          participant.getPosts().add(post);         participantRepository.save(participant); // добавил для наглядности, мы в транзакции, сохранит при commit и без .save()     }  }

 

4.       Как работает модуль.

Когда мы в клиентском коде написали нечто подобное:

 Participant participant = testEntityFactory.participantBy(RankType.WRITER)             .withName("customName")             .withPost("post_1")             .withPost("post_2")             .withPost("post_3")             .createOne();

Под капотом происходит следующее:

1. В первой строке мы создаем прототип. Сигнатура создания должна содержать набор параметров, который необходим для создания “минимально допустимой сущности”. Т.е. такой сущности, которую можно “заперсистить”, не получив исключение, что поле Х не должно быть null или какие-либо ещё валидации на уровне DB/ORM. В моём примере у participant обязан быть name и rank. Я решил, что rank я обязан задавать, а name — можно обойтись дефолтным значением.

2. С 2 по 5 строку, рассказываем, как мы хотим модифицировать “минимально допустимую сущность”. По дефолту есть метод with(), куда можно передать лямбду:

   public ParticipantPrototype with(Callback callback) {         chain.add(callback);         return this;     }

Если у вас имеются повторяемые лямбды, инкапсулируйте их в метод.

Если модификация простая, реализуйте её в методе:

  public ParticipantPrototype withName(String participantName) {         chain.add(participant -> participant.setName(participantName));         return this;     }

Если методу нужны другие спринговые бины, например Repository – передайте работу в ParticipantPrototypeService — он является спринговым бином, и в него можно инжектить через @Autowired.

 public ParticipantPrototype withPost(String customTitle) {         chain.add(participant -> participantPrototypeService.addPost(participant, customTitle));         return this;     }

Callback добавится в цепочку (List<Callback>), и будет вызван в терминальной операции.

3. Метод createOne — терминальная операция. FluentInterface ленивый, это значит, что обработка не терминальных операций начнется только тогда, когда начнёт работу терминальная операция. Таким образом мы получаем дополнительный контроль над созданием сущности и можем окружить всё создание в транзакцию.

@Transactional public List<Participant> create(ParticipantPrototype prototype) {

Более того, если нам надо создать несколько сущностей, мы можем попросить фабрику это сделать, при помощи метода createMany(int amount).

    /**      * terminal operations      */     public Participant createOne() {         this.amount = 1;         return participantPrototypeService.create(this).get(0);     }      public List<Participant> createMany(int amount) {         this.amount = amount;         return participantPrototypeService.create(this);     }

Далее ParticipantPrototypeFinisher, в транзакции, создает «минимально допустимую сущность», «персистит» её, заполняет дефолтными значениями, модифицирует при помощи заданной в клиентском коде цепочки не терминальных операций и отдаёт наверх.

Завершение

На примере реализации модуля для создания тестовых сущностей мы рассмотрели создание spring fluent interface pattern.

Данный подход позволяет писать красивый, декларативный, легко расширяемый код, который также позволяет:

1. В уже написанных тестах не отвлекаться на шум создания тестовых сущностей и видеть структуру только тех полей, которые важны для теста, а остальные поля, которые для теста не важны — будут иметь дефолтные значения.

2. В новых тестах, переиспользовать модуль и расширять, добавляя новые методы.

3. В случае изменения каких-то полей в сущностях – делать правку в одном месте – в “кишках” модуля. А не править сигнатуры по всему проекту, что пришлось бы делать, если используется классический статик утиль подход.

4. Инкапсулировать код, ответственный за создание тестовых сущностей, из класса, общего для всех SpringBootTest классов, в отдельный модуль.

5. Если ленивость не нужна — можно убрать список лямбд и выполнять работу сразу, тогда получится spring builder pattern.

Код можно посмотреть тут

Примеры в классе FluentInterfaceExampleTest.