Layered architecture

Layered architecture, слоистая архитектура. (todo: найти хоршие ссылки)

(todo: привести 100500ое описание слоёной архитектуры?)

Эргономичный код нарезан в том числе и на слои. Но в отличие от традиционной слоёной архитектуры, слои являются предпоследней гранулярностью (todo: перевод) нарезки, зачастую вырождающейся в нарезку на классы/объекты. Плюс в отличие от многих версий слоёной архитектуры, слой доступа к данным (ввод-вывод) поднят на один уровень с бизнес-логикой. Это сделано во имя "Очевидности и тестируемости": - Благодаря обращению к инфраструктурному слою напрямую из слоя приложения, становится Очевидно какие эффекты имеет функция - Благодаря удалению зависимости слоя бизнес-логики (где обычно находится вся сложность приложения) от слоя ввода-вывода, бизнес-логика становится Тестируемой.

Hexagonal (Ports&Adapters) architecture, Clean architecture, Onion architecture

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

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

В целом, я разделяю идею HOCA о том, что фреймворки должны быть задвинуты на задворки приложения (на самый внешний слой). Но если использование той или иной фичи фреймворка делает жизнь проще и не наносит ущерб Очевидности и Тестируемости, то я не вижу большого криминала в зависиомсти от фреймворка. Например, я считаю необоснованной технику, по абстрагированию логики транзакций в шлюзе вместо использования спрингового @Transactional (todo: ссылка на статю Маритна с примером).

Наконец дядюшке Бобу над отдать должное за Screaming architecture. На мой взгляд архитектура это слишком громкое слово, но я включаю этот принцип в тактические приёмы.

(todo: ревью: наверно стоит уделить внимание поподробнее чем они друг от друга отличаются)

Data, Context, Interaction Architecture

Оригинальная статья.

Эргономичный подход включает в себя DCI целиком в качестве устройства юз кейса по дефолту. Но так же как и в случае HOCA, эргономичный подход делает акцент на вынесении эффектов в юз кейс (контекст в терминах DCI) и как следствие на чистоте бизнес-логики (ролей в терминах DCI).

В чём эргономичный подход слегка расходится с DCI, так это в вопросе логики в объектах доменной модели. По DCI объекты должны быть "dumb, dumb, dumb", т.е. просто структурами данных. В эргономичном же подходе, доменные объекты во-первых, должны быть иммутабельными, и, во-вторых, должны защищать свои инварианты.

Domain Driven Desing

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

Но в отличие от DDD, в эргономичном подходе большая часть поведения уносится в роли DCI. Это сделано потому что подход DDD (помещения максимальной части бизнес-логики в сущности) плохо масшатабируется - у одной сущности может быть много ролей, и если все их засунуть в один класс, то он станет слишком большим. Кроме того анемичная модель является стандартом де факто в индустрии.

И так же как и в случае со всеми предыдущими идеями из ОО-сообщества, эргономичный подход в отличие от DDD делает акцент на чистых функциях.

На этом идеи ОО-лагеря закончены и переходим к ФП лагерю.

Simple Made Easy

Simple Made Easy, (краткий пересказ на русском).

На мой взгляд, Рич Хики - один из самых крутых чуваков в индустрии в наши дни. А этот доклад - один из самых крутых докладов Рича Хики.

Именно этот доклад первым навёл меня на ключевую мысль эргономичного подхода - разделение эффектов и логики. Кроме того в нём есть синхрония todo: нормальное слово в с DCI касательно, разделения структур данных и поведения.

Но я не разделяю мнение Хики о том, что типы бесполезны. На мой взгляд, типы снимают целый класс проблем при модификации кода, и, что ещё важнее, делают существенный вклад в Очевидность кода. Дополнительным плюсом является возможность создания эргономичных ИДЕ, что прекрасно ложиться на идею эргономичного кода.

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

Functional core, imperative shell (FCIS)

Boundaries, версии на русском я не нашёл.

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

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

Railway oriented programming

Оригинальная статья

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

Это наиболее низкоуровневая из базовых идей, которая применяется на уровне конкретных методов. Но её вклад в Очевидность настолько важен, что я включил её и в список базовых идей и концептуальную модель юз кейса.

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

Но в отличие от чисто функционального подхода на монадах, предлагаемого в этой серии статей, я за использование банальных ифов раннего возврата там, где они работают хорошо. А они работают хорошо в большинстве случаев. Я выбираю ифы, потому что условие и действие явно прописанные в коде более Очевидные, тем map, который может отработать или нет в зависимости от типа ресивера (todo: переписать по русски).

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

Процедурное программирование (todo: коммент)

(todo: качественно разботанить тему и обосновать почему ПП хорошо только для эффектов. Ну или убедиться в обратном и написать книгу о ПП:))

Объектно-ориентированное программирование

Если вы ни разу не слышали про ООП, то у меня для вась есть новости:) Если вы слышали про ООП, то, весьма вероятно, у меня для вас есть большие новости:)

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

Если вы что-то слышали про ООП, то наверняка слышали, что ООП это это программирование с классами и объектами. А принципы ООП это:

Некоторые особо продвинутые товарищи включают ещё и абстракцию.

Программа в целом в объектно-ориентированном подходе рассматривается как:

Звучит хорошо, но если вы пробовали применить эти подходы, то столкнулись с тем, что в реальном мире они не выживают.

Сначала рассмотрим классы и объекты. Класс - это матрица для создания объектов. А объект - это сущность, обладающая состоянием, поведением и идентичностью.

Но загляните в реальные проекты. В типовом проекте 90% классов это либо структуры данных без поведения, либо пакеты процедур без состояния и идентичности.

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

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

С наследованием ещё хуже - это инструмент, от которого больше вреда чем пользы (см. Effective Java, "Item 18: Favor composition over inheritance").

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

То есть применения рассмотренных техник программирования недостаточно, для того чтобы подход к разработке был объектно-ориентированным. Возможно дело в дизайне?

Дисклаймер - вообще да:). Но к озвученным выше подходам к дизайну возникает много вопросов и вот ключевые:

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

Так что же ООП это фикция? В моей карьере был период когда я так считал и благодаря этому периоду я плотно изучил функциональный подход. Но сейчас, после 15 лет изучения, практики и преподавания ООП/ООД, я начал понимать и снова верить в ООП.

Причиной тому послужили книги и статьи трёх других не менее авторитетных авторов:

Оба этих подхода утверждают, что программирование с объектами != программированию на классах и один объект дизайна в коде может превратиться в набор классов и их экземпляров.

OOSE такие наборы классов называет блоками, а DCI - контекстами.

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

OOSE выделяет три разных вида объектов - интерфейсы (уже в смысле интерфейса системы во внешний мир), сущности и контроллеры. DCI в свою очередь выделяет три других, но очень похожих видов объектов - Data, Context и Interactor. И если OOSE допускает реализацию объекта несколькими классами, то DCI прямо требует разделение объекта на 3 (и более, на самом деле, зависит от количества ролей) этих класса в коде.

Возможно в этот момент вы подумаете "Но группа связанных классов - это же модуль". В том-то и дело, что "классов". Статических структур времени компиляции. Во время выполнения же, модули инстанциируются в объекты (далее будем называть их блоками, чтобы не было путаницы). А то, что принято называть объектами, во время выполнения - может быть как объектом, так и структурой данных в хорошем смысле этого слова. Либо непосредственно с данными, либо со ссылками на методы. Объект превращается в блок, состоящий из структур данных в тот момент, когда становится слишком (todo: это сколько в граммах?) большим или приобретает поведение с разных уровней абстракции и/или консёрнов (todo: перевести на русский).

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

Так же как и множество объектов с собственным состоянием может быть порождено статическим конструктором класса, так и множество блоков может быть порождено статическим конструктором модуля. И так же как и класс, может переиспользовать объекты, подменяя им состояние (см Flyweight Design Patterns: Elements of Reusable Object-Oriented Software), так и модуль может переиспользовать часть объектов (поведения) создавая композиции, на основе синглтонов поведения и датахолдеров, загужаемых из БД по ИДу.

(todo: авторская вставка - не к месту. Или сноской сделать или утащить куда-нить) Наконец, блоки надо использовать только тогда, когда решаемая проблема не ложится на объекты. Если проблема хорошо ложится на объекты, то можно и нужно использовать их.

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

(todo: "мягкая" подводочка) Но как мы видим, ООП хорошо работает для проектирования крупных частей программы, а в деталях оно скатывается к процедурному программированию. И тут на сцену выходит функциональный подход.

Функциональное программирование

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

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

Второе чего мне не хватало в функцональном подходе - это тех самых крупных блоков-объектов из ООП из которых состоит программа во время выполнения. А составить программу из чистых функциональных пайплайнов не всегда получается.

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

Но для реализации Логики нет ничего более эргономичного, чем функциональный подход. Освобождение Логики от Эффектов делает её простой, понятной, локальной, тестируемой, более переиспользуемой и пригодной для параллельного исполнения. А что с Эффектами - главной ценностью, которую создают программы? Для реализации Эффектов нет ничего более эргономичного, чем процедурный подход.

(todo: расписать функциональное представление объектов - последовательность иммутабельных структур с общим идом и менеджер мутабельной ссылки на актуальное состояние)

Так мы приходим к мультипарадигменному подходу.

Мультипарадигменное программирование

Этот раздел начался с вопроса: "Какая же из этих парадигм позволяет писать эргономичный код?". Ответ - эргономичный код позволяет писать только комбинация всех мейнстримовых парадигм.

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

Функциональная парадигма используется для описания функций системы. То есть Логики, которая интересует заказчика.

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

(todo: чёт разделение Логики и Эффектов очень напоминает CQRS - надо обдумать)

(todo: прочитать Multi-Paradigm Design for C++ - мош я тут велосипед изобретаю)

Принципы проектирования системы

(todo: https://www.ics.uci.edu/~cs223/papers/cidr07p15.pdf - entity=component?)

Платформа

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

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

Порты

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

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

Порт может вызвать только один юз кейс. Если вам надо вызвать два юз кейса, значит у вас есть составной юз кейс.

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

(todo: обобщить на случай юз кейсов подсистем, вызываемых из юз кейсов первичной системы)

Адаптеры

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

Главной задачей адаптеров является исполнение Эффектов. Поэтому это единственные компоненты, которым разрешено обращаться к Платформе. Но как я писал ранее, разрешение на исполнение эффектов исключает сложную логику (todo: стиль)(todo: привести критерии определения сложности логики).

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

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

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

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

Логика

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

Логика не должна быть реализована в идиоматичном функциональном стиле - весь код в функциях, без переменных, только с неизменяемыми структурами данных, с монадами и их интерпретаторами, трнасдьсерами, зипперами и т.д. Более того, я против того, чтобы все эти абстрактные термины фигурировали в коде. Это детали реализации и они снижают отношение сигнал/шум и путают неинициированных, коих пока что большинство. Поэтому если любите классы и объекты - пожалуйста, императивные форы и ифы - я не против, изменяемые локальные переменные и массивы ради эффективности - я только за. Даже исключения и try-catch можно, но я бы хорошенько подумал, как обойтись без них. Ну и да логгирование тоже можно, при условии, что оно не является функцией вашей системы, значимой для конечного пользователя. Вобщем, при реализации логики надо следовать двум правилам:

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

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

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

Юз кейсы

Главной задачей кода реализации юз кейса явлется предельно ясное, декларативное описание юз кейса с точки зрения пользователя, а так же входных данных юз кейса и видимых эффектов, к которым приводит его выполнение. В идеале должно быть как в старых добрых книгах по XP и DDD - вы показываете код юзкейса заказчику и он его понимает в общих чертах. Для того чтобы код юз кейса был максимально приближен к языку пользователя, он не должен содержать низкоуровневых деталей и сложной логики.

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

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

Технически, юз кейс может быть представлен объектом без состояния, объектом с состоянием только в памяти, и объектом с состоянием во внешнем хранилище.

Первый тип наиболее простой и распространенный и подходит в случаях, когда всё состояние юз кейса хранится в объектах предметной области. В этом случае, единственный объект юз кейса создаётся платформой или приложением и инжектируется в порт. Затем порт может либо самостоятельно получить объекты предметной области и передать их в юз кейс, либо передать в юз кейс идентификаторы этих объектов (которые содержатся в событиях). Какой вариант лучше выбрать, зависит от конкретного случая.

Если же юз кейсу требуется какое-то состояние, которое не укладывается естественным образом в модель предметной области (todo: например?), то необходимо создать репозиторий юз кейсов, к которому будет обращаться порт, для получения объекта юз кейса. Репозиторий может быть как ин-мемори, так и персистентный. Ин-мемори вариант проще и быстрее, но персистентый позволяет юз кейсам переживать шатдауны и работать в много-нодовой среде. В случае персистентного юз кейса, можно состояние юз кейса выделить в отдельный объект и сохранять только его. Наконец, объекты юз кейсов с состоянием должны быть синхронизированы должным образом.

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

Я настоятельно рекомендую не использовать в юз кейсах какие-либо управляющие конструкции (todo: уточнить термин) за исключеним ROP-конструкций (конструкции вида if (error) return ErrorData) и условий отражающих описание юз кейса на естественном языке. В юз кейсах недопустимо использование блоков с уровнем вложенности более двух и вызов приватных методов (todo: стиль). Если в вашем описании юз кейса на естественном языке есть уровень вложенности больше двух - пересмотрите его.

(todo: изучить возможность использования корутин для описания много шаговых юз кейсов одним методом)

(todo: ROP вместо исключений отделяет ошибки предметной области от ошибок программирования)

Разбиение по видам классов

У меня нет однозначного и универсального рецепта разбиения классов по пакетам заранее. Но я точно могу сказать, что не надо разбивать проект по видам классов - entities, services, controllers. В особо одиозных случаях заводят пакеты exceptions, enums и annotations. Пакетов classes и interfaces почему-то ни разу не видел:) В плюсы такого подхода можно попытаться записать только то, что при его использовании не надо думать. Но, во-первых, в нашей работе это минус, а во-вторых, думать всё-таки надо - либо как привести класс к одному из существующих видов, либо придумать новый вид. К дизайну ни та ни другая деятельность отношения не имеет и я считаю, что время лучше посвящать продумыванию дизайна системы.

Проблемы пакетирования по видам классов:

Другие идеи к разбиению классов

Что касается правильного разбиения с самого начала проекта, то за вдохновением советую обратиться к:

Мой подход к разбиению классов

Открытые иерархии

Закрытые иерархии

qbit (todo)

Q5 (todo)

Удобно (todo)

Проект ТруСтори

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

public class WorkShift {

    private final @Nonnull WebSocket webSocket;

    private final @Nonnull User user;

    private final @Nonnull Duration maxInterruptionLen;

    private Instant @Nonnull startTime;

    private Instant @Nullable finishTime;

    public WorkShift(@Nonnull WebSocket webSocket, @Nonnull User user, @Nonnull Instant startTime, @Nonnull Duration maxInterruptionLen) {
        this.webSocket = webSocket;
        this.user = user;
        this.startTime = startTime;
        this.maxInterruptionLen = maxInterruptionLen;
    }

    public void onLogin() {
        if (finishTime == null) {
            // Первый логин, ничего не делаем
            return;
        }
        final Duration interruptionLen = Duration.between(finishTime, Instant.now());
        if (interruptionLen.toMillis() < maxInterruptionLen.toMillis()) {
            // Продолжение смены
            webSocket.sendKpi(user);
        } else {
            // Начало новой смены
            startTime = Instant.now();
        }
    }

    public void sendKpi() {
        webSocket.sendKpi(user);
    }

    public void onLogout() {
        finishTime = Instant.now();
    }

}

public class WorkShift {

    @Nonnull Instant startTime;

    @Nullable Instant finishTime;

    public WorkShift(@Nonnull Instant startTime) {
        this.startTime = startTime;
    }

    public WorkShift(@Nonnull Instant startTime, @Nonnull Instant finishTime) {
        this.startTime = startTime;
        this.finishTime = finishTime;
    }

    public WorkShift finish(Instant finishTime) {
        return new WorkShift(startTime, finishTime);
    }

}

public class KpiTracker {

    private final User user;

    private final WebSocket webSocket;

    private final Duration maxInterruptionLen;

    private WorkShift workShift;

    public KpiTracker(User user, WorkShift prev, WebSocket webSocket, Duration maxInterruptionLen) {
        this.user = user;
        this.workShift = prev;
        this.webSocket = webSocket;
        this.maxInterruptionLen = maxInterruptionLen;
    }

    public void onLogin() {
        if (workShift == null) {
            // Первый логин сотрудника, ничего не делаем
            workShift = new WorkShift(user, Instant.now());
            return;
        }

        if (workShift.finishTime == null) {
            // Ошибка - повторынй логин после начала смены, без предварительного логаута
            workShift = new WorkShift(user, Instant.now());
            return;
        }

        final Duration interruptionLen = Duration.between(workShift.finishTime, Instant.now());
        if (interruptionLen.toMillis() < maxInterruptionLen.toMillis()) {
            // Продолжение смены
            webSocket.sendKpi(user);
        } else {
            // Начало новой смены
            workShift = new WorkShift(user, Instant.now());
        }
    }

    public void sendKpi() {
        webSocket.sendKpi(user);
    }

    public void onLogout() {
        workShift = workShift.finish(Instant.now());
    }

}

// Т.к. реализация репозитория не имеет особого значения, привожу только интерфейс
new UserWorkShift(user, Instant.now());
public class UserWorkShiftRepository {

    @Nullable
    public UserWorkShift getByUserId(Long userId) {
        return null;
    }

}

public class KpiGateway {

    private final UserWorkShiftRepository userWorkShiftRepository;

    private final Duration maxInterruptionLen;

    public KpiGateway(UserWorkShiftRepository userWorkShiftRepository, Duration maxInterruptionLen) {
        this.userWorkShiftRepository = userWorkShiftRepository;
        this.maxInterruptionLen = maxInterruptionLen;
    }

    @Nullable
    public UserWorkShift getByUser(User user) {
        return userWorkShiftRepository.getByUserId(user.getId());
    }

    public void sendKpi(@Nonnull UserWorkShift userWorkShift) {
        // sendKpi
    }

    public Duration getMaxInterruptionLen() {
        return maxInterruptionLen;
    }

}

public class UserWorkShift {

    @Nonnull public final User user;

    @Nonnull public final Instant startTime;

    @Nullable public final Instant finishTime;

    public UserWorkShift(@Nonnull User user, @Nonnull Instant startTime) {
        this(user, startTime, null);
    }

    public UserWorkShift(@Nonnull User user, @Nonnull Instant startTime, @Nullable Instant finishTime) {
        this.user = user;
        this.startTime = startTime;
        this.finishTime = finishTime;
    }

    public UserWorkShift finish(Instant finishTime) {
        return new UserWorkShift(user, startTime, finishTime);
    }

}

public class KpiTracker {

    @Nonnull private final User user;

    @Nonnull private final KpiGateway kpiGateway;

    @Nullable private UserWorkShift userWorkShift;

    public KpiTracker(@Nonnull User user, @Nonnull KpiGateway kpiGateway) {
        this.user = user;
        this.kpiGateway = kpiGateway;
        userWorkShift = kpiGateway.getByUser(user);
    }

    public void onLogin() {
        if (userWorkShift == null) {
            // Первый логин сотрудника, ничего не делаем
            userWorkShift = new UserWorkShift(user, Instant.now());
            return;
        }

        if (userWorkShift.finishTime == null) {
            // Ошибка - повторынй логин после начала смены, без предварительного логаута
            userWorkShift = new UserWorkShift(user, Instant.now());
            return;
        }

        final Duration interruptionLen = Duration.between(userWorkShift.finishTime, Instant.now());
        if (interruptionLen.toMillis() < kpiGateway.getMaxInterruptionLen().toMillis()) {
            // Продолжение смены
            kpiGateway.sendKpi(userWorkShift);
        } else {
            // Начало новой смены
            userWorkShift =  new UserWorkShift(user, Instant.now());
        }
    }

    public void sendKpi() {
        if (userWorkShift == null) {
            // Ошибка - запрос на отравку КПИ для ни разу не логиневшегося сотрудника
            return;
        }
        kpiGateway.sendKpi(userWorkShift);
    }

    public void onLogout() {
        if (userWorkShift == null) {
            // Ошибка - логаут ни разу не логиневшегося сотрудника
            return;
        }
        userWorkShift = userWorkShift.finish(Instant.now());
    }

}

// Т.к. реализация репозитория не имеет особого значения, привожу только интерфейс
public class UserWorkShiftRepository {

    // ...

    public UserWorkShift save(@Nonnull UserWorkShift userWorkShift) {
        // ...
    }

    // ...

}

public class KpiGateway {

    // ...

    public UserWorkShift save(UserWorkShift userWorkShift) {
        return userWorkShiftRepository.save(userWorkShift);
    }

    // ...
}

public class KpiTracker {

    @Nonnull private final User user;

    @Nonnull private final KpiGateway kpiGateway;

    @Nullable private UserWorkShift userWorkShift;

    public KpiTracker(@Nonnull User user, @Nonnull KpiGateway kpiGateway) {
        this.user = user;
        this.kpiGateway = kpiGateway;
        userWorkShift = kpiGateway.getByUser(user);
    }

    public void onLogin() {
        if (userWorkShift.workShift == null) {
            // Первый логин сотрудника, ничего не делаем
            userWorkShift = userWorkShift.startNewWorkShift();
            kpiGateway.save(userWorkShift);
            return;
        }

        if (userWorkShift.workShift.finishTime == null) {
            // Ошибка - повторынй логин после начала смены, без предварительного логаута
            userWorkShift = userWorkShift.startNewWorkShift();
            kpiGateway.save(userWorkShift);
            return;
        }

        final Duration interruptionLen = Duration.between(userWorkShift.workShift.finishTime, Instant.now());
        if (interruptionLen.toMillis() < maxInterruptionLen.toMillis()) {
            // Продолжение смены
            kpiGateway.sendKpi(userWorkShift.user);
        } else {
            // Начало новой смены
            userWorkShift = userWorkShift.startNewWorkShift();
            kpiGateway.save(userWorkShift);
        }
    }

    // ...

    public void onLogout() {
        if (userWorkShift == null) {
            // Ошибка - логаут ни разу не логиневшегося сотрудника
            return;
        }
        userWorkShift = userWorkShift.finish(Instant.now());
        kpiGateway.save(userWorkShift);
    }

}

public class KpiRules {

    public boolean shouldStartNewWorkShift(UserWorkShift currentWorkShift, Duration maxInterruptionLen, Instant now) {
        if (currentWorkShift == null) {
            // Первый логин сотрудника, ничего не делаем
            return true;
        }

        if (currentWorkShift.finishTime == null) {
            // Ошибка - повторынй логин после начала смены, без предварительного логаута
            return true;
        }

        final Duration interruptionLen = Duration.between(currentWorkShift.finishTime, now);
        return interruptionLen.toMillis() >= maxInterruptionLen.toMillis();
    }

}

public class KpiTracker {

    @Nonnull private final KpiGateway kpiGateway;

    @Nonnull private final KpiRules kpiRules;

    @Nonnull private UserWorkShift userWorkShift;

    public KpiTracker(@Nonnull Long userId, @Nonnull KpiGateway kpiGateway, @Nonnull KpiRules kpiRules) {
        this.kpiGateway = kpiGateway;
        this.kpiRules = kpiRules;
        this.userWorkShift = kpiGateway.getByUserId(userId);
    }

    public void onLogin() {
        UserWorkShift currentWorkShift = userWorkShift();

        boolean shouldStartNewWorkShift = kpiRules.shouldStartNewWorkShift(currentWorkShift, kpiGateway.getMaxInterruptionLen(), Instant.now());
        Assert.isTrue(currentWorkShift != null || shouldStartNewWorkShift, "KPI rules has decided to not start new work shift on login of user without active work shift");

        if (shouldStartNewWorkShift) {
            currentWorkShift = new UserWorkShift(user, Instant.now());
            kpiGateway.save(currentWorkShift);
        } else {
            kpiGateway.sendKpi(currentWorkShift);

    }

    // ...

}

@RestController
public class KpiPort {

    private final AuthService authService;

    private final UserService userService;

    private final KpiGateway kpiGateway;

    public KpiPort(AuthService authService, UserService userService, KpiGateway kpiGateway) {
        this.authService = authService;
        this.userService = userService;
        this.kpiGateway = kpiGateway;
    }

    @EventListener
    public void onLogin(UserLoginEvent e) {
        final KpiTracker kpiTracker = new KpiTracker(userService.getUser(e.userId), kpiGateway, new KpiRules());
        kpiTracker.onLogin();
    }

    @PutMapping(value = "/kpi")
    public void sendKpi() {
        final KpiTracker kpiTracker = new KpiTracker(authService.getCurrentUser(), kpiGateway, new KpiRules());
        kpiTracker.sendKpi();
    }

    @EventListener
    public void onDisconnect(UserDisconnectEvent e) {
        final KpiTracker kpiTracker = new KpiTracker(userService.getUser(e.userId), kpiGateway, new KpiRules());
        kpiTracker.onLogout();
    }

    @EventListener
    public void onLogout(UserLogoutEvent e) {
        final KpiTracker kpiTracker = new KpiTracker(userService.getUser(e.userId), kpiGateway, new KpiRules());
        kpiTracker.onLogout();
    }


}

Todos (todo)

Анкл Боб

Эрик Майер

Дэвид Вест

Эрик Эванс

Кевлин Хэнни

Рич Хикки

Трюгве Реенскауг

Джеймс Коплейн (James Coplien)

DDD

Object Thinking

Lean Architecture for Agile Software Development

Clean Code

Clean Architecture

Effective Java

Practical API Design

Object-Oriented Design with Applications

Object-Oriented Analysis

Object-Oriented Software Engineering: Use Case Drive Approach

Working with objects: The OOram Software Engineering Method

Functional Design and Architecture

https://leanpub.com/functional-design-and-architecture

Design Patterns: Elements of Reusable Object-Oriented Software

Object-Oriented Software Engineering: Use Case Drive Approach

Domain Modeling Made Functional

Patterns, principles and practises of DDD

The Common Sense of Object Orientated Programming

Segue

Screaming architecture

Ссылка: https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html

DCI: Practical Tips and Lessons for Nerds

Ссылка: https://www.youtube.com/watch?v=SxHqhDT9WGI

A Glimpse of Trygve: From Class-oriented Programming to Real OO

Ссылка: https://www.youtube.com/watch?v=lQQ_CahFVzw

Clean Coders Hate What Happens to Your Code When You Use These Enterprise Programming Tricks

Ссылка: https://www.youtube.com/watch?v=FyCYva9DhsI

Giving code a good name

Ссылка: https://www.youtube.com/watch?v=CzJ94TMPcD8

OOP is Dead! Long Live OODD!

Ссылка: https://www.youtube.com/watch?v=RdE-d_EhzmA