@EntityGraph на методах репозитория

1. Когда нужен @EntityGraph вместо join fetch

Когда вы впервые побеждаете N+1 через join fetch, возникает ощущение: «Ну всё, жизнь удалась, можно ставить join fetch везде и жить счастливо». А потом вы ловите себя на том, что даже самый банальный findById вдруг превращается в JPQL‑портянку, и репозиторий начинает выглядеть как сборник заклинаний. @EntityGraph нужен как раз для ситуации, когда запрос простой, а план загрузки — нет.

Представьте себе типовой сценарий нашего shop-data-jpa. Мы хотим показать “карточку товара”: поля товара (sku, name, price, status) и название категории. Маппинг у нас правильный и осторожный: Product -> Category скорее всего LAZY (потому что не всегда нужна категория, и точно не хочется грузить её «вдогонку» случайно).

Если мы сделаем:

productRepository.findById(id)

то связь category может быть не загружена, и при первом обращении к product.getCategory() Hibernate отправит отдельный SELECT. Для одного товара это ещё терпимо, но для списков — это типичная дорожка в N+1.

Мы можем решить проблему через join fetch и написать JPQL. Но тут появляется учебно‑реальная неудобность: критерий “по id” и так уже идеально выражен стандартным репозиторным методом или derived query. Не хочется превращать простой метод в кастомный запрос только ради того, чтобы “подтащить” категорию.

И вот здесь полезно разделить две мысли.

- Первая мысль: логика выборки — это “кого” мы ищем (по id, по sku, по статусу).
- Вторая мысль: план загрузки — это “что должно быть готово” у найденного объекта до выхода из сервисного метода (категория, позиции заказа, товар в позиции заказа и т.д.).

@EntityGraph — это попытка сделать вторую мысль видимой и управляемой, не переписывая первую.

2. Что делает @EntityGraph

Когда вы видите слово “graph”, мозг новичка иногда рисует себе что-то страшное: “граф сущностей”, “граф зависимостей”, “граф проблем в моей жизни”. На практике всё проще: entity graph — это список связей, которые нужно загрузить сразу, в рамках конкретного чтения. @EntityGraph в Spring Data JPA — это аннотация, которой мы говорим: «Для этого метода репозитория загрузи вот эти association‑поля заранее».

Самое важное: @EntityGraph не меняет смысл запроса. Он не добавляет фильтры, не “подправляет” WHERE, не превращает findByStatus в “findByStatusAndSomethingElse”. Он влияет только на то, какие связи будут инициализированы внутри одного чтения.

Чтобы лучше это почувствовать, удобно держать в голове такой конвейер:

flowchart TD
    S["Service read use-case"] --> R["Repository method"]
    R --> Q["Query logic: WHERE / ORDER BY"]
    R --> F["Fetch plan: какие связи загрузить"]
    Q --> JPA["JPA provider: Hibernate"]
    F --> JPA
    JPA --> SQL["Generated SQL"]
    SQL --> PC["Persistence Context"]

Логика запроса отвечает на вопрос “какие строки/сущности мне нужны”. Fetch plan отвечает на вопрос “какие связанные данные должны быть загружены вместе с ними”.

attributePaths: как мы описываем, что грузить

В аннотации @EntityGraph есть ключевой параметр attributePaths. Это массив строк — путей к связям. Путь пишется как вы бы обращались к полям в Java, но строкой: "category", "items", "items.product".

Звучит легко, но в этом и сила, и опасность. Сила — потому что вы прямо на методе указываете нужную загрузку. Опасность — потому что очень легко начать писать “на всякий случай” "items.product.category.manufacturer.someOtherThing" и получить ненужную загрузку, которая внезапно станет вашим новым “почему всё медленно”.

Декларативность без магии

join fetch — это часть JPQL, вы явно пишете “как” вы хотите загрузить.
@EntityGraph — это декларация “что” вы хотите получить инициализированным. Hibernate (как провайдер JPA) под капотом обычно реализует это через join‑fetch (особенно для to-one связей), но важное в учебном смысле: вы отделяете план загрузки от текста запроса.

3. Базовый пример: карточка товара Product вместе с Category без JPQL

Когда мы говорим “карточка товара”, мы обычно имеем в виду use‑case: получить один товар и сразу иметь доступ к его категории внутри того же сервисного чтения. Это идеальный сценарий для @EntityGraph, потому что критерий выборки простой (по id), а нужная связь понятная (category).

Сначала напомню, как выглядит маппинг (упрощённо). Обратите внимание на LAZY: это наш default, а не “потом разберёмся”.

import jakarta.persistence.FetchType;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.ManyToOne;

public class Product {

    // Важно: LAZY — дефолтная «гигиена», чтобы не тащить категорию в каждом чтении товара.
    @ManyToOne(fetch = FetchType.LAZY)
    // Явно фиксируем FK-колонку, чтобы было понятно, откуда берётся связь на уровне БД.
    @JoinColumn(name = "category_id", nullable = false)
    private Category category;
}

Теперь — репозиторий. Мы не хотим писать JPQL, потому что критерий “по id” уже отлично выражается derived query. Сделаем отдельный “говорящий” метод именно под карточку и аннотируем его графом.

import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;

import java.util.Optional;

public interface ProductRepository extends JpaRepository<Product, Long> {

    // Говорим Spring Data JPA: при чтении карточки продукта заранее инициализируй связь category.
    @EntityGraph(attributePaths = "category")
    Optional<Product> findCardById(Long id);
}

Здесь важный момент, который часто удивляет новичков: часть имени до By может быть “человеческой”, а Spring Data всё равно распарсит критерий по части после By. Метод findCardById по смыслу всё так же ищет по id, просто имя честно говорит, что это чтение под карточку.

Теперь сервисный метод чтения. Нам важно, чтобы use‑case жил в транзакции (пусть и read‑only), и чтобы наружу не “утекало” незапланированное lazy‑чтение.

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

@Service
public class CatalogQueryService {

    private final ProductRepository productRepository;

    public CatalogQueryService(ProductRepository productRepository) {
        // Внедряем репозиторий как зависимость: use-case управляет чтением, не контроллер.
        this.productRepository = productRepository;
    }

    @Transactional(readOnly = true) // Важно: всё чтение происходит внутри persistence context.
    public String loadProductCategoryName(Long id) {
        // Используем метод с entity graph: ожидаем, что category уже будет инициализирована.
        Product product = productRepository.findCardById(id).orElseThrow();
        // Без графа здесь мог бы «выстрелить» лишний SELECT из-за ленивой связи.
        return product.getCategory().getName();
    }
}

Что мы выигрываем? В идеальном мире (и в нашем учебном мире с Hibernate 7 это как раз типично) вы увидите в SQL‑логах один запрос с join к таблице категорий, а не “сначала товар, потом отдельный select за категорией”.

Примерный силуэт SQL будет похож на:

select p.*, c.*
from product p
join category c on c.id = p.category_id
where p.id = ?

Пожалуйста, не воспринимайте это как «обязательный текст SQL» — конкретные алиасы и список колонок будут другими. Важно, что категория загружается сразу и product.getCategory().getName() не стреляет дополнительным запросом.

4. Вложенные attributePaths: карточка заказа CustomerOrder

Если пример с товаром кажется слишком “мягким”, то пример с заказом обычно сразу показывает, зачем вообще нужен осознанный fetch plan. Заказ (CustomerOrder) сам по себе почти никогда не интересен без позиций (OrderItem). А позиция заказа часто нужна вместе с товаром (product). То есть карточка заказа — это не один объект, а маленький, но конкретный граф.

Начнём с понятного: связи по умолчанию остаются LAZY. Заказ может иметь много позиций, и мы точно не хотим, чтобы каждое чтение заказа автоматически тащило их (а потом ещё товары, а потом категории, а потом производители, а потом… вы поняли).

import jakarta.persistence.FetchType;
import jakarta.persistence.OneToMany;

public class CustomerOrder {

    // Коллекция — потенциально «тяжёлая» связь, поэтому по умолчанию держим LAZY.
    @OneToMany(mappedBy = "order", fetch = FetchType.LAZY)
    private java.util.List<OrderItem> items;
}

Теперь в репозитории мы заводим метод “карточки заказа” и указываем граф. Здесь ключевой момент: вложенные пути.

import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;

import java.util.Optional;

public interface CustomerOrderRepository extends JpaRepository<CustomerOrder, Long> {

    // Инициализируем не только items, но и вложенную связь product внутри каждой позиции.
    // Это и есть «карточка заказа»: данные готовы в рамках одного чтения.
    @EntityGraph(attributePaths = {"items", "items.product"})
    Optional<CustomerOrder> findCardByOrderNumber(String orderNumber);
}

Смысл attributePaths здесь такой: сначала инициализируй коллекцию items, а для каждого OrderItem инициализируй product.

И да, это уже to-many загрузка. А значит, у неё есть цена. В большинстве случаев Hibernate реализует это через join‑ы, и вы получаете “широкий” результат, где одна строка заказа размножается на количество позиций на уровне строк SQL. В persistence context Hibernate потом аккуратно собирает это обратно в один объект CustomerOrder с коллекцией items.

Почему это нормально именно для карточки заказа? Потому что карточка — это один заказ, то есть размер результата ограничен. У заказа может быть 3 позиции или 20 — но это всё ещё “человеческий” объём, который мы можем позволить себе одним чтением.

Сервисный метод для такого read‑use‑case выглядит максимально скучно (и это хорошо, скучный код часто самый правильный):

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

@Service
public class OrderQueryService {

    private final CustomerOrderRepository orderRepository;

    public OrderQueryService(CustomerOrderRepository orderRepository) {
        // Репозиторий инкапсулирует доступ к данным, сервис — use-case и границы транзакции.
        this.orderRepository = orderRepository;
    }

    @Transactional(readOnly = true) // Важно: коллекции должны инициализироваться внутри транзакции.
    public int loadItemCount(String orderNumber) {
        // Читаем «карточку»: ожидаем, что items уже загружены графом.
        CustomerOrder order = orderRepository.findCardByOrderNumber(orderNumber).orElseThrow();
        // Если бы items не были загружены, тут мог бы быть ленивый SELECT (или даже N+1 в циклах).
        return order.getItems().size();
    }
}

Если вы включите SQL‑логи, вы должны увидеть, что вызов order.getItems().size() не вызывает “пачку дополнительных SELECT”. Он работает на уже загруженных данных.

И вот это ощущение — “данные готовы внутри use‑case” — и есть цель @EntityGraph. Мы не делаем внешний слой счастливым “случайно”, мы делаем сервисный read‑use‑case честным и предсказуемым.

5. Сочетания: derived, @Query, пагинация

Когда @EntityGraph начинает нравиться, возникает естественная тяга: “А давайте теперь просто навесим @EntityGraph на всё”. Это примерно как открыть для себя горячие клавиши в IDE и пытаться горячей клавишей делать кофе. Можно, но будет странно. Давайте аккуратно разберём несколько типовых сочетаний.

@EntityGraph + derived query (самый частый кейс)

Это “золотая зона” @EntityGraph: критерий выборки выражается именем метода, а план загрузки — аннотацией. Например, список активных товаров, где для каждого товара нужна категория.

import org.springframework.data.jpa.repository.EntityGraph;

import java.util.List;

public interface ProductRepository extends org.springframework.data.jpa.repository.JpaRepository<Product, Long> {

    // Для списка товаров подтягиваем to-one связь: это обычно безопаснее, чем тащить коллекции.
    @EntityGraph(attributePaths = "category")
    List<Product> findByStatus(ProductStatus status);
}

Для ManyToOne это обычно вполне безопасно. Категория — to-one связь, join не раздувает результат по строкам так, как коллекции. Это хороший компромисс между простотой кода и контролем загрузки.

@EntityGraph + @Query (когда JPQL нужен, но fetch хочется отдельно)

Иногда JPQL нужен не ради fetch, а ради условий или порядка, который трудно выразить derived‑методом. В таком случае можно сделать так: JPQL отвечает за “кого выбираем”, @EntityGraph — за “что подгружаем”.

import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.Query;

import java.util.List;

public interface CustomerOrderRepository extends org.springframework.data.jpa.repository.JpaRepository<CustomerOrder, Long> {

    // Граф отвечает за «что загрузить», а JPQL — за «кого выбрать».
    @EntityGraph(attributePaths = {"items", "items.product"})
    @Query("""
           select o
           from CustomerOrder o
           where o.status = :status
           """)
    List<CustomerOrder> findCardsByStatus(OrderStatus status);
}

Практический смысл в том, что вы не смешиваете в одном месте “условия” и “план загрузки”, особенно если один и тот же запрос переиспользуется с разными fetch‑потребностями.

Пагинация и @EntityGraph: осторожно с коллекциями

Здесь действует та же физика, что и у collection join fetch: Page по корневой сущности плохо сочетается с подгрузкой to-many коллекции. @EntityGraph не обходит это ограничение, он просто задаёт тот же fetch plan другим способом.

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

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.repository.EntityGraph;

public interface CustomerOrderRepository extends org.springframework.data.jpa.repository.JpaRepository<CustomerOrder, Long> {

    // Внимание: коллекция + Page часто приводит к «размножению строк» на SQL-уровне.
    @EntityGraph(attributePaths = "items")
    Page<CustomerOrder> findByStatus(OrderStatus status, Pageable pageable);
}

Для to-one связей пагинация обычно живёт спокойнее, а для коллекций — нет. Если вам нужна страница заказов, items почти никогда не стоит тянуть “по умолчанию”: сначала спросите себя, не нужен ли здесь вообще entity-граф, или честнее сразу читать summary/read-модель.

EntityGraphType: FETCH и LOAD

Когда вы открываете документацию, вы увидите, что у @EntityGraph есть параметр type. Обычно там два значения: FETCH и LOAD. Эта тема легко превращается в болото “а давайте изучим спецификацию JPA на 300 страниц”, но нам нужен короткий, рабочий смысл.

Главная идея такая: graph может либо жёстко задать, что грузить (и остальное считать lazy), либо добавить к стандартному плану загрузки из маппинга.

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

Пример (скорее “читабельность”, чем необходимость):

import org.springframework.data.jpa.repository.EntityGraph;

import java.util.Optional;

public interface ProductRepository extends org.springframework.data.jpa.repository.JpaRepository<Product, Long> {

    // Явно фиксируем тип графа, чтобы читатель видел намерение: загрузить только перечисленное.
    @EntityGraph(attributePaths = "category", type = EntityGraph.EntityGraphType.FETCH)
    Optional<Product> findDetailedById(Long id);
}

6. Практика @EntityGraph в shop-data-jpa

Когда команда впервые получает в руки инструмент управления загрузкой, обычно есть две крайности. Первая крайность — не использовать его вовсе и потом лечить N+1 паникой. Вторая крайность — навесить граф на всё подряд, и получить “избыточную загрузку”, только теперь легализованную. Нам нужна взрослая середина: @EntityGraph как часть контракта конкретного read‑use‑case.

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

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

И ещё один важный организационный момент: @EntityGraph — это не “чинить ленивость”, а проектировать чтение. Если вы чувствуете, что граф начинает разрастаться, это сигнал: либо use‑case слишком жирный, либо вы возвращаете слишком много данных “на всякий случай”.

7. Типичные ошибки при использовании @EntityGraph

Ошибка №1: думать, что @EntityGraph меняет условия запроса.
Иногда разработчик видит, что метод называется findByStatus, добавляет @EntityGraph, и ожидает, что “граф умнее загрузит только активные позиции” или “теперь будет другой join”. Нет: условия задаются запросом (derived или @Query), граф только говорит, что из найденной сущности нужно загрузить сразу. Если данные “не те” — проблема в WHERE, а не в графе.

Ошибка №2: делать один огромный “универсальный граф на всё”.
Очень соблазнительно: “А давайте сделаем граф {"items", "items.product", "items.product.category", ...} и будем вызывать один метод”. Это обычно заканчивается тем, что вы постоянно грузите лишнее, SQL становится шире, память течёт быстрее, а смысл use‑case размывается. Граф должен быть узким, как хороший контракт: ровно то, что нужно сейчас.

Ошибка №3: пытаться чинить постраничные списки заказов через загрузку коллекций.
@EntityGraph не отменяет физику SQL. Если вы просите страницу заказов и одновременно просите загрузить items, вы почти наверняка получите тяжёлое чтение. И да, это будет похоже на проблему “collection join fetch + pagination”, только теперь спрятанную в аннотацию. Граф удобнее всего работает для карточек и небольших, ограниченных чтений.

Ошибка №4: использовать @EntityGraph там, где вам вообще не нужна entity.
Если use‑case — “показать таблицу из трёх колонок”, то подгружать entity + связи и потом вручную “вырезать нужное” — это как купить пианино, чтобы сыграть один звук “ля”. Это рабоче‑технически возможно, но архитектурно странно. В таких сценариях обычно логичнее сразу читать в отдельную read‑модель, но это тема следующей лекции.

Ошибка №5: считать, что @EntityGraph заменяет транзакционную дисциплину.
Граф помогает загрузить нужные связи в момент чтения, но он не превращает объект в “вечноживущий портал в базу”. Если вы вышли из сервисного метода и начинаете “дочитывать” что-то, что не было в графе, вы всё равно упрётесь в ту же границу persistence context. Поэтому правильный порядок мыслей остаётся прежним: use‑case → транзакционная граница → план загрузки → инструмент.