Entity core и его стоимость

Entity core — что там живёт и почему

Кольцо Entities — самое внутреннее кольцо в Clean Architecture. Оно содержит общеприкладные бизнес-правила: логику, которая была бы верна и валидна в любом приложении, построенном на этом бизнес-домене, независимо от delivery mechanism или используемой инфраструктуры.

На B2B-платформе заказов Entity core содержит:

• Класс Order с инвариантами жизненного цикла (pending-заказ должен иметь хотя бы одну позицию перед подтверждением; отменённый заказ не может перейти в confirmed; итог должен равняться сумме позиций)
• Класс Invoice со структурными инвариантами (позиции должны суммироваться в итог; оплаченный счёт не может быть изменён)
• Value object Money с правилами арифметики с учётом валюты
• Перечисления OrderStatus, InvoiceStatus, представляющие валидные состояния
• Domain events (OrderConfirmed, InvoiceGenerated) как чистые структуры данных

Что отсутствует в кольце Entities: всё, что касается инфраструктуры, прикладного потока или фреймворка. Никаких вызовов репозиториев. Никакого async/await-обращения к базе данных. Никаких ORM-аннотаций @Column или @Entity. Никаких HTTP-статус-кодов. Никаких импортов фреймворка логирования. Классы entity — чистые объекты, которые могут работать в полностью изолированном тесте без внешних зависимостей.

Аргумент стабильности

Аргумент в пользу сохранения Entity core чистым — это аргумент стабильности: entities — последний код, который нужно трогать при технологических изменениях. Базы данных мигрируют. Веб-фреймворки обновляются. Появляются мобильные клиенты. Ни одно из этих событий не должно изменить правило «Итог Invoice должен равняться сумме его позиций». Это правило постоянно, пока держится бизнес-модель.

Сохраняя entities свободными от инфраструктурных импортов, вы гарантируете: обновление ORM не может вызвать изменения entity. Переход с REST на GraphQL не может потребовать касания бизнес-логики Order. Новое требование облачного провайдера не может пройти в domain-правила. Самое внутреннее кольцо меняется только при изменении бизнес-модели — что и является единственным изменением, которое должно правомерно затрагивать его.

Эта стабильность также даёт выигрыш в тестировании. Unit-тесты entity — самые дешёвые тесты в системе: инстанцировать domain object, вызвать метод, проверить результат. Никакой базы данных, HTTP-сервера, mock-фреймворка. Entity инкапсулирует свои инварианты — для их тестирования нужен только класс entity и любые value types, которые он использует.

Честная стоимость — маппинг и косвенное обращение

Структурные преимущества Clean Architecture реальны. Стоимость не менее реальна, и её необходимо признать перед выбором паттерна.

Налог на маппинг. Каждая граница кольца требует кода трансляции. Поле entity Order не появляется автоматически в OrderResponseModel (кольцо Use Cases), OrderDTO (REST-адаптер) или ORM-классе OrderRecord (адаптер базы данных). Код маппинга на каждой границе пишется явно. Поле, начинающееся на entity, обычно появляется в четырёх-пяти отдельных классах и требует трёх-четырёх функций маппинга.

В аудите B2B-платформы: добавление deliveryDeadline к entity Order означало:

1. Добавить поле в Order (кольцо Entities) с инвариантом (deadline должен быть после даты создания)
2. Добавить в GenerateInvoiceRequest и GenerateInvoiceResponse там, где нужно (кольцо Use Cases)
3. Добавить в OrderRecord и функцию ORM-маппинга (кольцо Infrastructure)
4. Добавить в OrderDTO и код сериализации (REST-адаптер)
5. Добавить в OrderGraphQLType и resolver (GraphQL-адаптер)

Это налог на косвенное обращение. В layered architecture можно затронуть два файла. В Clean Architecture затрагиваешь пять — в обмен на гарантию, что каждое кольцо не знает форматов других.

Церемония определений интерфейсов. Каждый репозиторий, каждый сервис, каждый output port требует определения интерфейса в кольце Use Cases и конкретной реализации в другом месте. Для системы с тридцатью use cases это тридцать интерфейсов input port, тридцать классов interactor, потенциально тридцать интерфейсов output port, тридцать request models и тридцать response models. Прежде чем написать единственную строку бизнес-логики, вы строите значительный объём структуры.

Когнитивная нагрузка. Новые инженеры, приходящие в команду, должны понять кольцевую модель, прежде чем смогут найти любой кусок логики. Вопрос онбординга «где живёт проверка billing hold?» имеет точный ответ (кольцо Use Cases, внутри interactor) — но только если понимаешь архитектуру.

Когда Clean Architecture избыточна

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

Избыточна для: CRUD-приложений. Система, которая создаёт, читает, обновляет и удаляет записи без сложных инвариантов, state machines жизненного цикла или нескольких delivery mechanisms, не имеет бизнес-логики для защиты. Entities без реальных инвариантов (просто getters и setters над строкой базы данных) не выигрывают от нахождения в чистом самом внутреннем кольце.

Избыточна для: небольших или краткосрочных приложений. Внутренний дашборд отчётности для десяти человек, скрипт миграции данных, throwaway proof-of-concept — они будут заменены до того, как долгосрочные преимущества архитектуры начнут накапливаться.

Избыточна для: команд без дисциплины поддержания границ. Преимущества Clean Architecture исчезают в момент, когда разработчик из удобства добавляет импорт фреймворка в entity. Налог на маппинг постоянен; структурные гарантии постоянны только при соблюдении dependency rule. Если команда не может или не будет соблюдать границы колец, стоимость платится, но выгода не получается.

Стоит того для: долгоживущих приложений со сложными domain-правилами. Когда бизнес-логика действительно сложна — несколько состояний жизненного цикла, инварианты, требующие соблюдения, правила, растущие со временем, — entity core обеспечивает стабильный фундамент, переживающий годы инфраструктурных изменений.

Стоит того для: нескольких delivery mechanisms над общим доменом. Четыре delivery mechanisms B2B-платформы (веб, мобильный, партнёрский API, CLI) переиспользовали одни и те же interactors. Добавление четвёртого механизма обошлось команде только одним адаптером. Без Clean Architecture у них было бы четыре копии логики генерации счёта.

Стоит того для: команд, которые будут расти и меняться. Когда команда, строящая систему, не та, что её поддерживает, явные контракты (request models, port interfaces) служат документацией, которую компилятор принудительно соблюдает.