Entity leakage и giant graphs

1. Anti-pattern и природа entity

Anti-pattern в persistence-коде — это не «компилятор ругается» и не «тесты красные». Это скорее стиль, который сегодня кажется удобным, а завтра превращает Hibernate в рулетку: SQL улетает «вдруг», графы сущностей раздуваются «сами», а простая правка в одном месте ломает производительность в другом. И да, самое коварное: такой код часто выглядит аккуратно и даже проходит code review, если смотреть только на Java-строчки, а не на то, какой SQL реально выполняется.

Важно поймать настроение: anti-pattern — это не обвинение разработчика в «грехе». Это диагноз того, что система потеряла управляемость. В persistence-слое это особенно больно, потому что ORM сам по себе неявный: у него есть flush, прокси, dirty checking, каскады, и он делает много «за вас». Если поверх этого добавить ещё и архитектурную неявность, получается эффект «двойной магии». Магия на магии — и в итоге вы не в волшебном мире, а в техподдержке.

Мы уже видели, что LazyInitializationException, N+1, неожиданные UPDATE и странный flush почти никогда не падают с неба. Обычно у них есть повторяющийся кодовый стиль, который заранее готовит проблему. Поэтому полезно смотреть на persistence-код не только глазами «работает / не работает», а глазами ревью: где именно use case теряет контроль над формой данных и местом, где потом выстрелит SQL.

К таким anti-pattern’ам полезно относиться прагматично: это сигналы, что границы use case размылись, а вместе с ними размылась и ответственность за форму данных. Самый базовый и самый распространённый случай — когда entity начинает жить не там, где ей положено.

Entity не «просто объект с полями»

Entity в Hibernate — это не «контейнер данных», который можно безопасно передавать куда угодно, как record или обычный DTO. Entity — это объект, который связан с механизмами ORM: он может быть managed внутри persistence context, может стать detached после окончания транзакции, а его ассоциации могут быть прокси-объектами и persistent-коллекциями. И это означает простую, но неприятную истину: вызов геттера может быть SQL-операцией, а изменение поля может закончиться UPDATE (даже если вы не звали save()).

На уровне проекта Commerce Persistence Lab это особенно хорошо видно на заказах. Заказ (PurchaseOrder) почти всегда связан с клиентом (Customer) и позициями (OrderItem). В домене это выглядит как «ну логично же», но для Hibernate это уже граф: минимум две ассоциации, и обе чаще всего LAZY, чтобы не делать список заказов в стиле «принеси мне весь интернет».

import jakarta.persistence.*;
import java.util.Set;

@Entity
class PurchaseOrder {

    // Клиента обычно не нужно поднимать при каждом чтении заказа, поэтому LAZY
    // Важно: обращение к customer может триггерить SQL, если прокси ещё не инициализирован
    @ManyToOne(fetch = FetchType.LAZY)
    private Customer customer;

    // Позиции заказа — типичный источник случайных запросов (size(), итерация, toString() и т.д.)
    // Поэтому по умолчанию тоже LAZY
    @OneToMany(mappedBy = "order", fetch = FetchType.LAZY)
    private Set<OrderItem> items;
}

Пока вы работаете с таким объектом внутри транзакции, Hibernate может спокойно догружать нужное. Но как только вы начинаете передавать entity наружу и использовать её как «универсальный объект для чтения», вы переносите решение «что загружать и когда» в случайное место: в форматирование строки, в лог, в маппер, в сериализацию, в дебаггер. И именно здесь начинается следующая тема — entity leakage.

2. Entity leakage: утечка и непредсказуемый SQL

Entity leakage — это ситуация, когда entity выходит за пределы слоя, где она должна жить (persistence/write-логика), и становится универсальным переносчиком данных: «возьмём entity, а дальше как-нибудь разберёмся». На словах это звучит экономно: «не будем плодить DTO». На практике это означает, что форма данных перестаёт быть частью use case и превращается в побочный эффект того, какие геттеры кто-то вызовет позже.

Вот пример, который на первый взгляд выглядит прилично. Сервис читает заказ и отдаёт его вызывающему коду. Транзакция read-only, всё «красиво».

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
class OrderReadService {

    @Transactional(readOnly = true)
    public PurchaseOrder getOrder(Long id) {
        // Возвращаем entity наружу: дальше кто угодно может дёргать lazy-поля и получать SQL «в неожиданном месте»
        return orderRepository.findById(id).orElseThrow();
    }
}

Проблема не в том, что метод «неправильный» синтаксически. Проблема в том, что теперь любой внешний код получает entity и может сделать с ней всё что угодно: прочитать customer, пройтись по items, залезть в product у каждого item, вызвать toString(), положить в лог, сериализовать в JSON — и каждый из этих шагов может стать SQL-операцией.

И вот здесь начинается самое коварное: внешний код обычно не выглядит как «работа с базой данных». Он выглядит как строка, которая просто что-то печатает.

// Внешний код «просто формирует строку», но на самом деле может инициировать загрузку коллекции
String text = order.getOrderNumber() + " / items=" + order.getItems().size();
// Потенциально: SELECT ... FROM order_item WHERE order_id = ?

Строка безобидная, как котёнок. Но если items — lazy-коллекция, то size() будет триггером инициализации. А значит, SQL уйдёт не в «слое данных», а в месте, которое вообще не подозревало, что оно сейчас работает с БД.

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

flowchart LR
    A["Внешний код
(логирование / форматирование / маппинг)"] -->|дергает геттер| B["Entity
PurchaseOrder"]
    B -->|lazy init| C["Hibernate Session / EntityManager"]
    C --> D[(PostgreSQL)]

Как только entity «утекла», Hibernate превращается в скрытого соавтора вашего кода. А скрытые соавторы — это всегда риск. Они, конечно, иногда помогают, но чаще приходят ночью и меняют результат без предупреждения.

Ещё один неприятный эффект утечки: внешний код может начать менять entity «для удобства». Например, кто-то решит «переименовать поле» перед отдачей, установить вычисленное значение, подправить статус для отображения. Если entity в этот момент остаётся managed (или транзакция ещё открыта), Hibernate может сделать UPDATE. И вы получите сценарий «почему в базе изменилось поле, если я только строил ответ?». Это тот самый класс accidental update, который мы обсуждали в модуле про dirty checking — только тут он приходит не от маппера внутри сервиса, а от “случайного” кода снаружи.

3. Giant entity graphs: «одна модель обслужит всё»

Giant entity graph — это не отдельная аннотация и не «особый режим Hibernate». Это последствия того, что entity превратили в универсальную read-модель. Как это обычно происходит? Очень постепенно и очень по-человечески: сначала у вас есть список заказов, потом «ну давайте в списке покажем email клиента», потом «и количество позиций», потом «и название первого товара», потом «и адрес доставки», а потом кто-то просит экспорт в CSV «со всем». И в этот момент вы обнаруживаете, что одна entity-модель пытается обслужить несовместимые сценарии.

Удобно держать в голове простую таблицу. Она не про «как правильно», а про то, что разные use case требуют разной формы данных, и это нормально.

С giant graphs связано ещё одно неприятное наблюдение: когда форма данных определяется «по месту использования», разработчики начинают пытаться «подстелить соломку» и заранее загрузить вообще всё, чтобы никто нигде не упал на lazy. Это ощущается как забота о коллегах, но заканчивается тем, что загрузка становится непредсказуемой и тяжёлой, а любые изменения ломают производительность.

На нашем домене giant graph выглядит почти как карта метро, где вы случайно купили билет «на все станции мира». Например, один заказ может потянуть клиента, адреса клиента, позиции заказа, продукты в позициях, детали продукта, категории продукта через link entity… и всё это внезапно становится «потенциально нужно», потому что entity утекла наружу:

flowchart TD
    O[PurchaseOrder] --> C[Customer]
    C --> CA[CustomerAddress]
    O --> I[OrderItem]
    I --> P[Product]
    P --> PD[ProductDetails]
    P --> PCA[ProductCategoryAssignment]
    PCA --> CAT[Category]

Giant graph — это не обязательно «всё загружается всегда». Это хуже: это когда вы вынуждены думать, что всё может понадобиться, потому что не вы контролируете точку обхода графа. А значит, вы теряете способность предсказывать SQL по коду сервиса. И для persistence-слоя это почти смертный приговор: если вы не предсказываете SQL — вы не управляете системой.

4. Случайная сериализация: toString(), логирование, JSON

Случайная сериализация — это когда entity-граф обходится не потому, что «бизнес-логике нужны данные», а потому что кто-то хотел «просто красиво вывести». Самые популярные триггеры: toString(), логирование и сериализация в JSON. И самый неприятный момент тут в том, что все три выглядят как чисто технические детали, не связанные с базой данных. Именно поэтому они особенно опасны.

Начнём с toString(). Если toString() у entity выводит всё подряд (или, хуже того, выводит коллекции), то обычный лог может внезапно инициировать lazy loading. А вы будете смотреть на SQL trace и думать: «кто вызвал этот запрос?», хотя ответ — «логгер».

Поэтому в учебном проекте мы сознательно держим toString() максимально скучным. Да, скучный toString() — это добродетель. В конце концов, наша задача — чтобы SQL был предсказуемым, а не чтобы строка для логов выглядела как роман Толстого.

@Override
public String toString() {
    // Принцип: не лезем в ассоциации и коллекции (customer/items), иначе логирование станет источником SQL
    return "PurchaseOrder{id=%d, orderNumber='%s'}".formatted(id, orderNumber);
}

Второй триггер — логирование через шаблоны, где логгер сам вызывает toString().

// Важно помнить: {} заставит логгер вызвать toString() у объекта
log.info("Closing order: {}", order); // Вызовет order.toString()

Если toString() «жадный», то логирование становится операцией чтения из БД. Причём в самом неприятном месте: в обработке ошибок, в finally, в диагностике. То есть ровно там, где вам меньше всего хочется ещё одного запроса.

Третий триггер — JSON-сериализация. Здесь нам важна одна мысль: как только вы отдаёте entity наружу (например, в web-слой), сериализатор начинает обходить геттеры и ассоциации. Он не знает, что такое «ваш use case», он знает только «мне нужно превратить объект в JSON». И если объект — entity-граф, сериализатор будет честно идти по графу. Иногда до бесконечности (циклы), иногда до LazyInitializationException, иногда до N+1.

Важно поймать главный смысл: случайная сериализация появляется как следствие entity leakage. Пока entity живёт там, где должна, вы можете контролировать загрузку. Но если entity превращается в транспортный контейнер данных, то любой инструмент «красивого вывода» внезапно становится частью вашего ORM-поведения.

5. Возвращаем контроль: явная read-модель

Отсюда и первый нормальный рефлекс: если use case читает данные, наружу должна уходить не «живая» entity, а форма чтения, которую этот use case действительно обещает. Entity хороша там, где вы меняете объект внутри транзакции. Для summary, списка, отчёта или внешней выдачи она обычно слишком тяжёлая и слишком непредсказуемая.

Иногда хватает даже очень узкой read-модели:

// Фиксированная форма чтения: здесь нечему лениво догружаться и нечему внезапно ходить в БД
public record OrderSummary(Long id, String orderNumber, String customerEmail) { }

После этого внешний код может сколько угодно читать поля summary, и от этого не появится новый SQL. Здесь важен сам принцип: форма данных должна быть зафиксирована там, где вы проектируете чтение, а не вычисляться потом через случайные вызовы геттеров у entity.

И projection тоже не магия. Как только вы тянете вложенные свойства и связанные данные, вы уже выбираете join, ширину SELECT и фактическую стоимость чтения. То есть контроль не исчезает — он просто возвращается туда, где ему и место.

6. Типичные ошибки при работе с entity

Ошибка №1: «Давайте просто вернём entity — потом разберёмся».
Такой подход почти всегда начинается как экономия времени, а заканчивается тем, что точка загрузки данных плавает по проекту. Сегодня геттер вызывается внутри транзакции и «всё ок», завтра кто-то вызвал его после транзакции и поймал LazyInitializationException, послезавтра другой человек включил какой-нибудь инфраструктурный костыль и получил десятки запросов в неожиданном месте.

Ошибка №2: лечить утечку entity аннотациями сериализации и “заплатками”.
Очень хочется «быстро починить», добавив где-нибудь @JsonIgnore, ещё где-нибудь @JsonManagedReference, а потом ещё несколько исключений — и вроде бы JSON снова отдался. Проблема в том, что вы лечите симптомы, а не причину. Если use case должен отдавать summary — отдавайте summary. Если должен отдавать детали — отдавайте детали. А не пытайтесь превратить entity-граф в универсальный швейцарский нож для всех форм выдачи.

Ошибка №3: делать toString() “красивым” за счёт обхода графа.
У entity нет обязанности быть «самоописывающимся объектом, который печатает всё». У entity есть обязанность быть предсказуемой в рамках ORM. Если toString() дергает lazy-коллекции или связанные сущности, вы превращаете логирование в SQL-сценарий. Это редко того стоит, даже если очень хочется удобный дебаг.

Ошибка №4: путать «read-объект» и «объект для изменения».
Entity — отличный кандидат для write-сценария: вы загрузили агрегат в транзакции, изменили поля, Hibernate сделал dirty checking и отправил UPDATE. Но для чтения списка или summary entity обычно слишком тяжёлая и слишком опасная. Когда вы смешиваете эти роли, появляются giant graphs и непредсказуемость, а следом — попытки “сделать всё EAGER” или “загрузить всё заранее”.

Ошибка №5: создавать “giant DTO”, который один в один копирует entity-граф.
Иногда разработчик вроде бы понял идею “не отдавать entity”, но вместо этого делает DTO размером с энциклопедию: OrderDto включает клиента, адреса клиента, позиции, продукты, детали продуктов, категории… и всё это в каждом сценарии. Формально entity уже не утекла, но проблема формы данных осталась: use case всё ещё не определён. DTO должен быть не «копией домена», а отражением конкретного чтения.