Відкладене завантаження to-one: proxy і SQL

1. Вступ

Уявіть, що ви відкриваєте звичайний бек-офісний екран: список замовлень, картку товару, швидкий перегляд клієнта. У початківця-розробника часто виникає благородне бажання: «Давайте завантажимо все одразу, щоб потім уже точно не довелося». В ORM-світі це бажання дуже швидко перетворюється на звичку тягнути за собою половину бази, навіть коли потрібне лише одне поле.

Hibernate, своєю чергою, намагається бути практичним. Він не прагне перетворювати кожен ваш find() на величезний комбайн із JOIN-ів і гігантського графа об’єктів. Тому в нього є така стратегія: якщо зв’язок позначено як LAZY, спочатку можна дати вам посилання, а дані завантажити пізніше — коли ви справді до них звернетеся. У людському сенсі це і є lazy loading.

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

Ми вже бачили, що managed-об’єкт живе разом із persistence context, а detached — уже ні. Тепер це знання стає дуже практичним: lazy-посилання вміє дочитувати дані лише доти, доки живий цей контекст. Саме звідси потім виникають і пізній 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 може повернути proxy замість справжнього 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. А клієнта підвантажувати лише тоді, коли бізнес-код справді звернеться до даних клієнта.

Є ще одна тонкість, пов’язана з кешем першого рівня. Якщо 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

// Proxy є "Customer" з точки зору instanceof
System.out.println(customer instanceof Customer);       // true

// Але реальний клас буде згенерований Hibernate (підклас/обгортка proxy)
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. Ініціалізація proxy: момент реального SQL

Головна інженерна точка в to-one lazy loading — це момент ініціалізації proxy. Ініціалізація — це коли Hibernate розуміє: «Окей, розробник справді поліз за даними, час робити SELECT». Ззовні це виглядає майже завжди однаково: ви викликаєте якийсь getter на об’єкті, і раптом у SQL-логах з’являється запит до пов’язаної таблиці.

Класичний приклад на замовленні й клієнті:

import jakarta.persistence.EntityManager;

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

// Тут зазвичай ще немає SELECT по customer: це посилання/proxy
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-трасування (профіль sql-trace на нашому стенді), картина зазвичай така:

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

-- 2) звернулися по email клієнта — Hibernate ініціалізує proxy і дозавантажує дані
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(); // часто proxy

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, то ініціалізація proxy може пройти без 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(): спочатку у вас є посилання на пов’язаного клієнта, а читання бізнес-полів може статися пізніше. Для сценаріїв запису це особливо корисно, тому що інколи нам потрібен саме зовнішній ключ, а не всі поля клієнта.

Як встановити зв’язок без зайвого читання

To-one lazy — це не лише історія про читання. Вона ще й про запис: Hibernate вміє працювати із зовнішніми ключами так, щоб не завантажувати пов’язану сутність, якщо вам потрібно лише послатися на неї. Це особливо корисно у сценаріях запису, коли у вас є 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 зв’язках

Proxy та lazy loading — це місце, де багато хто втрачає довіру до ORM, бо поведінка здається непередбачуваною. Насправді вона передбачувана, просто незвична: SQL прив’язаний не до рядка коду «в репозиторії», а до моменту, коли ви справді зажадали дані. Нижче — найчастіші помилки, які я бачу в новачків (і часом у себе в старих проєктах, де я теж колись був новачком).

Помилка №1: вважати, що order.getCustomer() означає «клієнта вже завантажено».
Дуже хочеться думати, що getter завжди повертає повноцінний об’єкт. Але в lazy-моделі getter часто повертає proxy. Тому правильне питання не «чи отримав я посилання?», а «чи вже зажадав я бізнес-дані пов’язаної сутності?». Getter зв’язку — не доказ SQL, а лише точка, де Hibernate може підставити замінник.

Помилка №2: робити висновок «дані точно в пам’яті», бо поле не null.
Hibernate рідко залишає lazy-зв’язок як null, бо null — це інше бізнес-значення: «зв’язку немає». Proxy якраз дає змогу зберегти сенс зв’язку («клієнт існує і пов’язаний»), але відкласти читання даних. Тому «не null» в ORM-коді — це ще не «ініціалізовано».

Помилка №3: дивуватися «раптовому SELECT» на першому зверненні до поля клієнта.
Щойно ви викликаєте getEmail(), getStatus(), getFirstName() і будь-які інші «справжні» поля, Hibernate має забезпечити коректність даних. Він не може їх «вгадати». Тому він чесно виконає SQL. Це не «зайвий запит», а плата за те, що ви обрали lazy-підхід і відклали завантаження.

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

Помилка №5: не помічати, що IDE/відладчик може спровокувати звернення до даних.
У дебагері інколи хочеться розгорнути об’єкт і подивитися поля. Деякі режими відображення можуть непрямо чіпати getters або обчислювати значення для показу, і ви раптом бачите в логу SQL «сам по собі». Насправді це ви — точніше, ваш відладчик — попросили дані. У Hibernate-світі це не мистика: перше реальне звернення до даних ініціює завантаження.