Lazy loading to-one: proxy и SQL

1. Введение

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

Hibernate, в свою очередь, пытается быть практичным. Он не хочет каждое ваше find() превращать в огромный комбайн из JOIN-ов и гигантского графа объектов. Поэтому у него есть стратегия: «если связь помечена как LAZY — я могу сначала дать тебе ссылку, а данные подтяну потом, если ты реально полезешь за ними». Это и есть lazy loading в человеческом смысле.

Здесь важно не перепутать. Lazy loading — не про «Hibernate никогда не загрузит связанную сущность». Lazy loading — про отложенный момент загрузки. Hibernate как бы говорит: «Сейчас ты спросил про заказ. Держи заказ. А клиента я принесу только если ты попросишь его e-mail, имя, статус… и вообще хоть что-то кроме id».

Мы уже видели, что managed-объект живёт вместе с persistence context, а detached — уже нет. Теперь это знание становится очень практичным: lazy-ссылка умеет дочитывать данные только пока этот контекст жив. Именно из этого потом вырастают и late SQL на обычном getter, и LazyInitializationException, когда контекста уже нет.

2. To-one связи в Commerce Persistence Lab

Чтобы lazy loading не оставался абстракцией, мы будем держаться за конкретные связи из нашего учебного проекта Commerce Persistence Lab. В нём есть два очень характерных to-one сценария: заказ знает своего клиента, а товар знает свои подробности. Для базовой механики будем опираться прежде всего на PurchaseOrder.customer: у ManyToOne lazy-поведение обычно видно честнее и стабильнее. Product.details полезен как вторичный кейс, но у @OneToOne(fetch = FetchType.LAZY) поведение сильнее зависит от конкретного маппинга и поддержки провайдера, поэтому не будем делать из него главный эталон. Оба случая жизненные: в заказе часто нужен customerId, но не всегда нужна вся карточка клиента; у товара часто нужен name и price, но подробности (описание, характеристики) нужны только на детальном экране.

Начнём с самого типичного варианта — ManyToOne: заказ → клиент. На уровне сущностей это выглядит так:

import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.ManyToOne;

@Entity
public class PurchaseOrder {
    @Id
    private Long id;

    // LAZY: Hibernate может вернуть прокси вместо реального Customer
    @ManyToOne(fetch = FetchType.LAZY)
    private Customer customer;
}

Ключевая строка здесь — fetch = FetchType.LAZY. Она означает: Hibernate имеет право не загружать Customer вместе с PurchaseOrder.

Посмотрим и на OneToOne — товар → подробности товара. Это полезный вторичный сценарий: в нашем проекте ProductDetails хорошо отделяет «карточку товара» от «списка товаров», где подробности реально нужны не всегда.

import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.OneToOne;

@Entity
public class Product {
    @Id
    private Long id;

    // LAZY: details могут быть подгружены только при реальном обращении к данным
    @OneToOne(fetch = FetchType.LAZY)
    private ProductDetails details;
}

Здесь важно понимать общий принцип: to-one связь — это всегда поле-объект, не коллекция. В Java это выглядит «невинно»: private Customer customer; — ну подумаешь, просто ссылка. Но именно в этом месте Hibernate получает возможность подложить вместо «настоящего клиента» специальный объект-заместитель.

3. FetchType.LAZY: поле не null, данных ещё нет

Когда начинающий разработчик впервые встречает FetchType.LAZY, он часто ожидает чего-то вроде «поле будет null, пока мы его не загрузим». Но Hibernate — не библиотека по ручной ленивой инициализации. Он не будет заставлять вас писать if(customer == null) loadCustomer(). Вместо этого он старается сохранить для вас удобство объектного мира: поле не null, но это может быть не полностью загруженный объект.

Давайте посмотрим на базовый сценарий:

import jakarta.persistence.EntityManager;

// Загружаем заказ: Customer при LAZY может не читаться из БД целиком
PurchaseOrder order = entityManager.find(PurchaseOrder.class, 10L);

// Получаем ссылку на связь (часто это proxy, а не "настоящий" Customer)
Customer customer = order.getCustomer();

System.out.println(order.getId());       // 10 (это поле точно было прочитано)

На этом месте многие подсознательно делают вывод: «Раз customer не null, значит клиент уже прочитан из БД». И вот тут начинается основная ловушка. order.getCustomer() может вернуть не настоящего Customer, а proxy-объект, в котором ещё нет e-mail, имени и всего остального. То есть в вашей руке — не «клиент», а «визитка клиента», на которой написан его id и номер телефона ORM-диспетчера: «если понадобятся детали — позвони, организуем чтение из базы».

Почему это удобно Hibernate’у (и нам тоже)? Потому что в момент загрузки заказа из базы чаще всего достаточно прочитать только таблицу заказов. Например, чтобы показать orderNumber, status, createdAt. А клиента подгружать только если бизнес-код действительно полез за данными клиента.

Есть ещё одна тонкость, которая упирается в first-level cache. Если Customer уже был загружен в текущий persistence context (например, вы ранее делали find(Customer.class, 5L)), то обращение к order.getCustomer() может моментально «разрешиться» в уже существующий managed-объект и не делать дополнительный SQL. То есть lazy не означает «обязательно будет второй запрос», lazy означает «у Hibernate есть свобода решать: грузить сейчас или потом».

4. Proxy-объект: «дублёр», который играет Customer

Чтобы понимать, где будет SQL, полезно знать, что такое proxy на уровне «какой объект у меня в переменной». Proxy в Hibernate — это объект-заместитель, который выглядит как сущность, но внутри содержит минимум информации и умеет «догрузиться» из базы при первом серьёзном обращении. Если проводить аналогию, то это актёр-дублёр: на сцене уже кто-то стоит, но настоящие реплики начнутся только когда понадобится крупный план.

В Java это обычно реализуется так: Hibernate создаёт подкласс вашей сущности (или объект, совместимый с ней), который перехватывает вызовы методов. Поэтому вы можете увидеть удивительное:

Customer customer = order.getCustomer(); // на практике это часто прокси

// Proxy является "Customer" с точки зрения instanceof
System.out.println(customer instanceof Customer);       // true

// Но реальный класс будет сгенерирован Hibernate (подкласс/прокси-обёртка)
System.out.println(customer.getClass().getName());      // ...Customer$HibernateProxy$...

В комментариях я бы ожидал примерно такой вывод:

System.out.println(customer instanceof Customer);  // true
System.out.println(customer.getClass().getName()); // com.example.commerce.customer.entity.Customer$HibernateProxy$...

То есть instanceof Customer — true, потому что proxy ведёт себя как Customer. Но getClass() показывает не ваш «чистый» Customer, а «специальную версию» от Hibernate.

Почему это важно? Потому что proxy — это главный способ Hibernate реализовать мысль «дай ссылку сейчас, загрузи позже». В proxy обычно уже известен идентификатор (тот самый customer_id из таблицы purchase_order), и proxy знает, к какой Session/EntityManager он привязан, чтобы потом сходить в базу.

Пока вы смотрите на proxy как на «нормального клиента», вы будете постоянно удивляться: «почему метод вдруг делает SQL?». Как только вы начинаете думать «у меня в руках может быть proxy», всё становится спокойнее и предсказуемее. Это не хаос. Это просто отложенная работа.

5. Инициализация прокси: момент реального SQL

Главная инженерная точка в to-one lazy loading — это момент инициализации прокси. Инициализация — это когда Hibernate понимает: «окей, разработчик реально полез за данными, пора делать SELECT». Снаружи это выглядит почти всегда одинаково: вы вызываете какой-то getter на объекте, и внезапно в SQL-логе появляется запрос к связанной таблице.

Классический пример на заказе и клиенте:

import jakarta.persistence.EntityManager;

PurchaseOrder order = entityManager.find(PurchaseOrder.class, 10L);

// Здесь обычно ещё нет SELECT по customer: это ссылка/прокси
Customer customer = order.getCustomer();

System.out.println(customer.getId());           // 5 (часто без SELECT: id уже известен по FK)
System.out.println(customer.getEmail());        // тут может уйти SELECT: нужны реальные поля

Обратите внимание на getId() и getEmail(). Почему getId() часто обходится без SQL? Потому что id уже известен: он был прочитан вместе с заказом как значение внешнего ключа customer_id. Hibernate может вернуть его из proxy, не загружая всю строку клиента.

А вот getEmail() — это уже бизнес-данные клиента. Если они ещё не загружены, Hibernate вынужден сделать запрос.

Если вы включили SQL trace (профиль sql-trace из нашего стенда), картинка обычно такая:

-- 1) загрузили заказ (прочитали customer_id как внешний ключ)
select po.id, po.customer_id
from purchase_order po
where po.id = 10;

-- 2) полезли за email клиента — Hibernate инициализирует прокси и догружает данные
select c.id, c.email, c.first_name, c.last_name
from customer c
where c.id = 5;

Чтобы сделать «инициализацию» совсем очевидной, можно использовать маленькую Hibernate-подсказку Hibernate.isInitialized(...). Это не обязательный инструмент «на каждый день», но для обучения он прекрасен: вы буквально видите, инициализирован объект или ещё нет.

import org.hibernate.Hibernate;

Customer customer = order.getCustomer(); // часто прокси

System.out.println(Hibernate.isInitialized(customer)); // false: данные ещё не загружены
customer.getEmail();                                  // триггер SQL (если данных ещё нет в persistence context)
System.out.println(Hibernate.isInitialized(customer)); // true: после инициализации поля доступны без доп. SELECT

Типичный вывод будет таким:

System.out.println(Hibernate.isInitialized(customer)); // false
customer.getEmail();                                  // (SQL ушёл в БД)
System.out.println(Hibernate.isInitialized(customer)); // true

Ещё один важный момент: если клиент уже загружен в persistence context, то «инициализация» прокси может пройти без SQL. Hibernate скажет: «ага, Customer#5 у меня уже есть managed-объектом, держи его», и запрос не понадобится. Это прямое продолжение модели identity map.

6. Практика: чтение, запись, модель

find() и getReference() как «ручная» версия

Этот паттерн уже знаком по order.getCustomer(): сначала ссылка, потом при первом реальном доступе к данным может появиться SQL. find() и getReference() показывают ту же идею в лоб: find() читает сущность сразу, а getReference() сначала даёт ссылку и откладывает чтение данных.

Customer eagerLike = entityManager.find(Customer.class, 5L);        // SELECT сразу
Customer lazyLike = entityManager.getReference(Customer.class, 5L); // ссылка без немедленного SELECT

System.out.println(eagerLike.getEmail()); // данные уже в памяти
System.out.println(lazyLike.getId());     // id обычно известен без SELECT
System.out.println(lazyLike.getEmail());  // тут уже может понадобиться SELECT

Поэтому order.getCustomer() по ощущению ближе к getReference(), чем к find(): сначала у вас ссылка на связанного клиента, а чтение бизнес-полей может случиться позже. Для write-сценариев это особенно полезно, потому что иногда нам нужен именно внешний ключ, а не чтение всей строки клиента.

Как установить связь без лишнего чтения

To-one lazy — это не только история про чтение. Она ещё и про запись: Hibernate умеет работать с внешними ключами так, чтобы не загружать связанную сущность, если вам нужно лишь сослаться на неё. Это особенно полезно в write-сценариях, когда у вас есть customerId, и вы создаёте заказ, не трогая все поля клиента.

Представим типичный сервисный сценарий: «создать новый заказ для клиента с id=5». Если вы написали код наивно, то вы можете сначала загрузить клиента, а потом присвоить его заказу. Но иногда это лишнее: если по бизнес-логике вам не нужно проверить статус клиента и не нужны его поля, можно просто сослаться на него.

Вот минимальный вариант:

import jakarta.persistence.EntityManager;

Customer customerRef = entityManager.getReference(Customer.class, 5L);

PurchaseOrder order = new PurchaseOrder();
order.setCustomer(customerRef);

entityManager.persist(order);

Обратите внимание: здесь мы не делали find(Customer.class, 5L). Мы не читали e-mail, имя и статус клиента. Мы просто сказали Hibernate: «вот ссылка на клиента #5, вставь её как FK в заказ». И Hibernate вполне может сделать INSERT в purchase_order с колонкой customer_id = 5, не выполняя SELECT по customer.

В SQL-логе это часто выглядит примерно так:

insert into purchase_order (customer_id, id) values (5, 123);

И всё. Без «а давайте сначала прочитаем клиента». Это не «оптимизация ради оптимизации», это просто корректное использование ORM-модели: связь хранится в базе как внешний ключ, и чтобы записать внешний ключ, не нужно обязательно тащить всю строку связанной таблицы.

Конечно, если вам нужно проверить, что клиент активен, или вам нужно использовать его e-mail для бизнес-логики — тогда чтение неизбежно и даже полезно. Но важна свобода: Hibernate даёт вам возможность разделить «сослаться» и «прочитать данные».

Ментальная модель «ссылка ≠ данные»

Если вы встраиваете lazy loading в голову, главное — перестать читать код «как простую Java». В чистой Java order.getCustomer() действительно означает «у меня есть объект Customer». В Hibernate это означает «у меня есть объект, который может быть proxy и может привести к SQL, когда я полезу за данными».

Вот аккуратная схема того, что происходит при to-one lazy:

flowchart TD
    A["SELECT purchase_order (загрузили заказ)"] --> B["order.customer = proxy (известен customer_id)"]
    B --> C{"Нужны данные клиента?"}
    C -->|"нет"| D["Работаем дальше без SQL к customer"]
    C -->|"да: getEmail()/getStatus()..."| E["proxy инициализируется через Session"]
    E --> F["SELECT customer WHERE id = ?"]
    F --> G["proxy теперь инициализирован, данные в памяти"]

И ещё одна маленькая табличка, которая помогает «поймать» момент SQL глазами:

Если вы держите эту модель, дальше становится проще читать любой код сервиса: вы буквально видите места, где «невинный» getter может быть точкой SQL. И вы перестаёте удивляться: «почему запрос уехал не в репозитории?».

7. Типичные ошибки при работе с lazy-proxy в to-one связях

Прокси и lazy loading — это место, где многие «теряют доверие» к ORM, потому что поведение кажется непредсказуемым. На практике оно предсказуемое, просто непривычное: SQL привязан не к строке кода «в репозитории», а к моменту, когда вы потребовали данные. Ниже — самые частые ошибки, которые я вижу у новичков (и иногда у себя в старых проектах, где я тоже когда-то был новичком).

Ошибка №1: считать, что order.getCustomer() означает «клиент уже загружен».
Очень хочется думать, что getter всегда возвращает «полноценный объект». Но в lazy-модели getter часто возвращает proxy. Поэтому правильный вопрос не «получил ли я ссылку?», а «требовал ли я уже бизнес-данные связанной сущности?». Getter связи — не доказательство SQL, он лишь точка, где Hibernate может поставить заместителя.

Ошибка №2: делать вывод «данные точно в памяти», потому что поле не null.
Hibernate редко оставляет lazy-связь как null, потому что null — это другое бизнес-значение: «связи нет». Прокси как раз позволяет сохранить смысл связи («клиент существует и связан»), но отложить чтение данных. Поэтому «не null» в ORM-коде — это ещё не «инициализировано».

Ошибка №3: удивляться «внезапному SELECT» на первом обращении к полю клиента.
Как только вы вызываете getEmail(), getStatus(), getFirstName() и любые другие «настоящие» поля, Hibernate должен обеспечить корректность данных. Он не может их «угадать». Поэтому он честно сделает SQL. Это не «лишний запрос», это оплата за то, что вы выбрали lazy-подход и отложили загрузку.

Ошибка №4: использовать getReference() как будто это find() и ожидать, что данные уже внутри.
getReference() часто берут как «быстрый find», а потом в следующей строке читают ref.getEmail() и удивляются, что ушёл запрос. Смысл getReference() именно в том, что он даёт вам ссылку без чтения. Если вы в следующей же строке читаете бизнес-поля — вы просто отложили SQL на одну строку вперёд, и это нормально. Просто важно понимать, что вы делаете.

Ошибка №5: не замечать, что IDE/отладчик может «спровоцировать» обращение к данным.
В дебаггере иногда хочется раскрыть объект и посмотреть поля. Некоторые режимы отображения могут косвенно трогать getters или вычислять отображаемые значения, и вы вдруг видите в логе SQL «сам по себе». На самом деле это вы (точнее, ваш отладчик) попросили данные. В Hibernate-мире это не мистика: первый реальный доступ к данным инициирует загрузку.