Луковичная архитектура в компоновке backend-приложения и куда в итоге класть маперы

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

— Контроллер это точка входа. В одном классе-контроллере могут быть несколько public-методов. Это позволяет соблюдать принцип high cohesion и переиспользовать private-методы — поиск сущности по id из запроса или проверка доступа.

— В контроллер пробрасывается объект сервиса с бизнес-логикой. Бизнес-логика находится в сервисах, а не в сущностях. Список методов сервиса соответствует списку методов класса-контроллера. Один метод класса-контроллера это точка входа для вызова соответствующего метода сервиса. Другой контроллер для работы с той же сущностью подразумевает другой сервис, если нельзя свести к вызовам существующего. Например, для админки сущности нужен другой сервис с действиями CRUD, не тот, который используется для пользовательской части. У пользователя, как правило, нет возможности произвольно изменять любые поля.

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

— DTO, соответствующее правилам валидации, передается в метод сервиса. Это позволяет в реализации бизнес-логики полагаться на то, что данные валидны, и в случае ошибок просто бросать исключение с записью в лог. Сообщения пользователю должны отправляться только на этапе валидации. Из этого правила есть исключение, когда в реализации бизнес-логики нужно вызвать сторонний сервис и вернуть пользователю его результат. Для этого можно использовать агрегирующий класс наподобие монады Either, объект которого возвращается из сервиса.

— С таким подходом типизированные исключения в реализации бизнес-логики становятся не нужны. Исключения должны сообщать об исключительной ситуации и носить технический характер. Например "ServiceUnavailableException", "NullPointerException", но не "ValueLessThanZeroValidationException".

— Из контроллера в метод сервиса передается сущность, с которой нужно сделать бизнес-действие. Внутри сервиса сущность по id не подгружается, так как от отсутствия сущности зависит ответ контроллера.

— Идеальный поток выполнения, это когда любая сущность за время запроса загружается один раз (хаки c кэшем ORM не считаются). Один и тот же runtime-объект передается и в слой контроля доступа, и в слой валидации, и в слой бизнес-логики. Это же относится к валидации — если для валидации понадобилось подгрузить какую-то связанную сущность, не нужно ее еще раз подгружать в сервисе с бизнес-логикой. Это означает, что в процессе валидации появляются артефакты, которые можно использовать далее, и это нормально. Без преобразований входных данных нельзя провалидировать даже простой int, пришедший в виде строки из HTML-формы. А если мы уже сконвертировали string в int, нет смысла это выбрасывать и конвертировать снова в бизнес-логике.

— Автоподгрузка связей в сущности при обращении к ним часто приводит к проблеме N+1. Желательно ее вообще отключить, указывать нужные связи в запросе ORM или подгружать их явно через соответствующий репозиторий.

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

interface UserService {
  fun save(user: User);
  fun update(user: User);
  fun get(id: UUID);
  fun delete(id: UUID);
}

Раз есть дублирование, то это выглядит как неправильный подход. Сервис с бизнес-логикой должен работать с сущностью, а не искать ее по id. Чтобы удалить сущность по id, надо сначала в контроллере ее подгрузить и проверить что она есть, а если нет, то выдать 404. Также может потребоваться валидация дополнительных полей, например сущность нельзя удалять, если она находится в некотором статусе. А раз уже подгрузили, то ее можно передавать в сервис.

Загрузка по id это ответственность репозитория. Репозиторий это абстракция над массивом сущностей, получение по id это аналог получения элемента массива по индексу. В сервисе может быть метод view(User $user), например если нам надо увеличить счетчик просмотров.