Эргономичная архитектура (v3.0.0)

Это классический пример агрегата - заказ и его позиции, упражнение и его шаги из (Trainer Advisor)

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

Связь, когда на одну "ключевую" сущность навешивается вспомогательная фича-сущность. Пример из TA - клиенты и их журналы.

Характеризуется, что в UI обычно отображается разными компонентами и компонент для многих сущностей имеет пагинацию или ленивую загрузку в том или ином виде.

Так же пример, навешивания вспомогательной сущности к ключевой. Например, в TA я сейчас делаю интеграцию с Яндекс.Формами, который нужна настройка в виде емейла терапевта в Яндексе. И хоть и жизненный цикл сущности настроек полностью ограничен ж/ц сущности терапевта, эти данные не нужны в каждом контексте и система благополучно прожила несколько лет без настроек.

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

Это очень важная техника, которая предотвращает появление сущностей на 100+ полей (тру стори из последнего проекта), из которых вам в каждом конкретном контексте (операции) надо от силы с десяток.

Другим примером частым, когда сущность может иметь невладеющую связь 1-к-1 является ссылка на справочник.

В качестве примера из ТА можно взять терапевтические задачи, на которые ссылаются приёмы, программы и записи в журнале.

И те и другие (интуитивно) не входят в логический агрегат терапевтический задачи - мы не хотим, чтобы при удалении ТЗ удалялись все приёмы, программы и записи журнала.

На самом деле, является скрытой реализацией связи немногие-ко-многим, которая, как правило, появляется когда одна из сущностей является справочной (пользовательским перечислением).

В качестве примера можно взять посты и тэги - у одного тэга может быть неограниченное количество постов. А вот для одного поста сложно более десятка тэгов.

Пример из ТА - программы и упражнения. Программы состоят из нескольких упражнений, а упражнение может входить в неограниченное кол-во программ.

И при том, что жц программы дефакто ограничен жц программы - нельзя создать программу раньше упражнения, он ограничен жц произвольного упражнения - можно добавить новое упражнение и добавить его в программу, после чего удалить первое упражнение, после явного исключения его из программы.

На самом деле большинство джоин-таблиц обеспечивают не связь многие-ко-многим, а связь немногие-ко-многим.

А настоящие же связи как правило многие-ко-многим естественным образом обретают собственные атрибуты и превращаются в самостоятельные агрегаты, с невладеющей связью один к одному.

Примером такой связи в ТА из параллельной реальности, в которой клиент может ходить на приёмы к разным терапевтам является агрегат приёма (в текущей реализации, клиент жёстко привязан к терапевту, который добавил его в систему). В этом случае, приём по большому счёту является связью многие-ко-многим между терапевтами и клиентами. Однако у него есть собственные атрибуты - дата, терапевтическая задача и т.д., которые превращают его в самостоятельную сущность.

Чтобы придумать реальный пример связи многие-ко-многим без атрибутов - надо постараться и в рамках потока сознания у меня не вышло.

В Проекте Э с медицинским дневником было несколько типов событий - замер, приём пищи, приём лекарств, активность и т.д.

Это один полиморфный агрегат.

В Проекте Р, который является чем-то в духе доменно специфичной джирой или сервисом для службы поддержки, задачи могут быть разных типов, и динамически менять свой тип в процессе своей жизни и даже одновременно быть сразу нескольких типов. Такие штуки моделируются как агрегаты для каждого типа, включая корневой, в котором листовый типы связаны с корнем невладеющим отношением один-к-одному.

Более конкретный, но вымышленный пример из TA. Сейчас есть похожая конструкция, где агрегат терапевта (содержит только имя) связан с агрегатом пользователя (содержит логин/пароль) невладеющим отношением один к одному.

Это сделано во многом в качестве заточки на то, что когда-нибудь у клиентов появится личный кабинет и они тоже смогут логиниться, но не обязаны при этом становиться терапевтами.

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

Например, файлы в TA хранятся в двух местах - метаинформация в PostgreSQL и собственно блобы в минио.

Соответственно агрегат файла представлен в системе составным ресурсом FilesStorage, который включает в себя два простых ресурса FilesMetaDataDao (сейчас в коде FilesMetaDataRepo) и MinioClient.

Продолжая пример с файлами из ТА, публичный ресурс ExercisesRepo (сейчас в коде ExercisesService) включает в себя два ресурса - ExercisesDao (сейчас ExercisesRepo) и _[Exercises]_FilesStorage, который в свою очередь состоит из FilesMetaDataDao и MinioClient

Заканчивая пример с файлами в ТА, экземпляры класса ресурсов могут входить в несколько ресурсов и даже хранить данные "в одном месте", при условии, что эти наборы данных не пересекаются. В ТА таким примером является FilesStorage, который является частью и ресурса ExercisesRepo и ресурса ClientFilesRepo.

Закодировано это тем, что класс FilesStorage (точнее интерфейс и его реализация) вынесен в платформу и не является Spring-бином. Бины же соответствующих ресурсов определены в Spring-конфигах этих ресурсов и имеют соответствующие имена.

А на уровне хранилища наборы данных файлов клиентов и упражнений разнесены по разным бакетам, которыми конфигурируются экземпляры FilesStorage.

Для технических агрегатов одного логического агрегата (два агрегата, связанные не владеющей связью один к одному) заводится один ресурс.

Примером такого ресурса является HotelsRepo (в коде сейчас HotelsService), который отвечает за хранение отелей и их номеров, коих может быть сотни.

Для ключевых агрегатов зачастую необходимо навешать множество разной логики при их изменении.

Например, в Проекте Э при добавлении, изменении или удалении события дневника, данные необходимо переслать в три разных системы. И потенциально таких систем может быть много.

Теоретически, все эти четыре штуки - репоз событий и клиенты систем можно собрать в один большой ресурс. Но в этом случае есть "интуитивная" проблема - ресурс станет слишком большим, и объективная проблема - у операции появится 4 точки отказа, ошибки в которых надо обрабатывать.

Поэтому в этом случае есть смысл применить паттерн доменных событий - операции модификации ресурса только модифицируют ресурс через второй внутренний ресурс публикуют сообщение об изменении агрегата. Которе перехватывается тремя разными портами и через соответствующие ресурсы прокидываются в соответствующие внешние системы.

В этом случае ресурс агрегата событий делается составным и включает в себя DAO-для хранения агрегатов и клиент очереди сообщений для публикации событий. А в случае если необходимо обеспечить гарантированную пересылку (как в Проекте Э) и требуется паттерн Transactional Outbox, то заводится ещё и ресурс-DAO для работы с таблицей-outbox-ом.

Иногда бывает так, что необходимо обеспечить какой-то инвариант над всей коллекцией агрегатов.

Самый простой и распространённый пример - обеспечение уникальности вторичного ключа агрегата. В этом случае самый простой и разумный способ это сделать делегировать эту работу СУБД.

Но бывают более сложные случаи. Например, в ТА, необходимо исключить пересечение приёмов по времени. С точки зрения надёжности, это опять же лучше сделать на уровне БД, но такое решение приведёт к утечке бизнес-логики в БД, чего в общем случае лучше избегать. Плюс придётся программировать на pl/sql :)

Поэтому в качестве альтернативы, эту проверку можно унести на уровень ресурса.

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

И при обновлении сквозного поля необходимо создать новые версии таблиц по всей цепочке.

И вот эта вся машинерия помещается на уровень ресурса и реализуется в соответствии с процедурной моделью.

Продолжая пример из предыдущего раздела.

На уровне бизнес-логики эти таблички представлены агрегатом, корнем которого является сущность таблицы, у которой есть объект-значение версии и список сущностей строк таблицы. И это собственно то, как таблица выглядит в голове у пользователей и в UI.

Однако в корневой таблице может быть до 1000 строк и в дереве декомпозиции может быть до 5 уровней. А в системе есть операция изменения одного поля одной строки. И если бы эта операция создавала бы полную копию агрегата со всей 1000 строк, во всех 5 таблицах в цепочек, то она бы генерировала 5000 новых строк, из которых только 5 имеют новые значения.

Поэтому на уровне БД, есть вспомогательная таблица - версия строки, которая связывает таблицу, строку и её значения. И для работы с этой таблицей введён примитивный ресурс-DAO, который работает с информацией, которая напрямую не видна через АПИ или доменную модель.

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

В этом случае стоит завести вспомогательную структуру данных (объект, DTO, DPO, представление), который включает в себя весь набор данных и код загрузки этого объекта сделать доменной операцией в виде метода companion-object этого объекта.

Продолжая пример из Проекта Р, там надо таблицы отдавать таблицы в двух разных контекстах примерно, но не совсем одинаково - для UI надо отдать саму таблицу, сгруппированную специальным образом плюс название сущности, с которой она связана и информацию о колонках таблицы (которые настраиваются динамически), а во внешную систему надо отдать только саму таблицу (с той же группировкой), но без дополнительных данных.

Соответственно код загрузки данных для группировки из других агрегатов оформлен в виде метода companion object-а класс RowsGroupsMetaData (доменной операции)

Строго говоря, операция обновления состоит из двух эффектов - чтения и записи.

И из этих соображений, если есть операции, которые меняют разные части агрегатов, то они все должны быть оформлены отдельными классами-операций, реализация методов которых тривиальна и идентична:

Это дублирование можно сократить, заведя абстрактный класс операции MyAggUpdateOp, который через Template Method получает специализированный код обновления агрегата.

А можно сделать проще - утащить этот код на уровень ресурса. Это будет метод, который на вход получает ид агрегата и лямбду создания обновлённой версии агрегата. А дальше делает всё тоже самое.

Бывает так, что функциональность ресурса может быть полностью реализована каким-то библиотечным (явно или косвенно) классом. Например ресурс репозитория и клиента, очевидно, может быть реализован (прощу прощения за каламбур) интерфейсом Spring Data-репозитория или декларативного HTTP-клиента. Но при этом, детали реализации могут утечь через API ресурса.

В случаях когда вы не планируете менять реализацию ресурса, это хоть и спорное, но на мой взгляд приемлемое решение.

А вот в случаях, когда планируете - протечки деталей реализации через АПИ лучше избегать.

Так было в Проекте Р (новом сервисе) и Проекте Ю (старом огромном монолите).

В частности, для своей логики работы Проекту Р, надо было доставать ключевые сущности Проекта Ю.

И изначально была гипотеза, что Проект Р может стать Проектом Ю 2.0 и, соответственно, новая кодовая база может стать владельцем ключевой сущности.

Но на текущий момент, ключевыми сущностями владеет Проект Ю и Проект Р достаёт их через REST API с помощью декларативного Spring HTTP-клиента.

И потенциально, сам этот интерфейс мог бы стать ресурсом, но через него течёт деталь реализации - ему в качестве параметров явно надо передать два значения, которые попадают в заголовки и используются для аутентификации запроса.

Поэтому в Проекте Р я завёл CoreEntitiesRepo, который на вход получает принципала (который в любом случае нужен для хитрой логики авторизации доступа конкретного пользователя к конкретному агрегату) и просто прокидывает вызов в клиента, кастуя принципала к текущей реализации, содержащей значения заголовков и прокидывая их в параметры.

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

В своей практике я пока что встречался только с одним типом кейсов - хранение долгоживущих токенов аутентификации во внешней системе.

В этом случае в классе ресурса заводится приватное поле в которое сохраняется токен или их набор.

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

Соответственно, в системе был ресурс ExternalSystemClient, у которого был внутренний ресурс ExternalSystemTokensCache, который хранил мапу с токенами. И при запросе на отправку данных во внешнюю систему, клиент шёл в кэш, тот смотрел в мапу, если находил возвращал токен из неё, а если не находил или найденный токен был протухший, то шёл во внешнюю систему и получал новый токен.

Здесь же для того чтобы избежать цикла в зависимостях, реализация клиента внешней системы (которая инкапсулировала в себе специфику HTTP-запросов) пришлось разделить на два класса - для запросов аутентификации и для запросов отправки данных.

Если в метод транформации закрался вызов метод чтения - его вызов надо заменить на аналогичный параметр. см. вынесение чтения из бизнес-логики.

Если в методе трансформации условно нужен большой кусок данных, его можно так же передать параметром, но параметр при этом сделать ленивым. см. Ленивые вычисления для реализации функциональной архитектуры.

Если в методе трансформации безусловно нужен "большой" список (много маленьких или мало больших объектов) - вместо списка можно передать функцию (Key) → Data и в трансформации использовать её для загрузки данных.

Это фактически смешает бизнес-логику и io и может привести к проблемам с производительностью, но взамен сократит срок жизни объектов и снизит потребление памяти.

Так сделана загрузка картинок в трансформации генерации docx-а с программой. В этом случае распарщенные изображения всё равно хранятся в памяти в течении всего времени работы метода, но так хотя бы их сырые можно выкинуть (через ГЦ) после парсинга.

Если датасет не помещается в память - добро пожаловать в потоковую обработку данных.

В простом случае это просто:

Здесь resizeImages - это оркестрация, findAllAsSeq и saveAll - ввод-вывод, а toBufferedImage и resizeTo - трансформация.

Но бывает так, что вам надо взять данные из нескольких источников, хитро и условно их склеить и обработать, разложить по разным местам и не забыть обработать ошибки. Тогда добро пожаловать в ад.

Тут уже, имхо, без разницы что у вас будет императивная мешанина логики и вывода, что адский конструктор адского конвейера, который собирает простые блоки - тут уже каждый выживает как может.

Если в метод трансормации закрался вывод - надо собрать параметры этого вызова в структуру данных и добавить её в возвращаемое значение метода. см. Шаг 3: выделение записи связки коробок с коробами из бизнес-логики.

Если у вас ввод-вывод перемешался с трансформациями - пакетируйте чтение и запись и оттесните их к началу и концу метода соответственно, а потом выделите середину с логикой в отдельную функцию.

см. Приведение кода к сбалансированной форме, выделение логики вместо DIP.

В зависимости от ситуации, пакет app может быть разбит на подпакеты по следующим принципам:

Изначально разбивается по ресурсам. Потом - как-то. Как вариант можно вдохновиться идеями из этапа оптимизации кластеров алгоритма кластеризации диаграммы эффектов.

Класс представляющий ресурс помещается в корень пакета. Если ресурс является ресурсом агрегата, то сущности помещаются в подпакет model, представления в подпакет views, а классы доступа к данным (если это не корневой класс ресурса, работающий с моделью) - в подпакет persistence. При необходимости можно завести подпакет commands.