Семантика save і методів за id

1. Семантика методів репозиторію

Якщо чесно, назви методів Spring Data схожі на англійські слова, які «і так зрозумілі»: save — зберегти, find — знайти, exists — існує. Проблема в тому, що в шарі доступу до даних «зрозуміло» — це не те саме, що «передбачувано». Один метод може піти в базу, інший — ні, третій — піде пізніше, коли ви цього зовсім не очікували.

Ваша задача як backend-розробника — не просто вивчити набір методів, а вміти ставити собі одне коротке запитання: що саме я хочу дізнатися про сховище або зробити з ним просто зараз? Якщо ви навчитеся чути зміст (семантику), то перестанете писати код, який робить два SQL-запити замість одного, або який раптово падає не там, де ви його викликали.

Щоб це зафіксувати, будемо мислити так: кожен метод репозиторію — це формалізоване запитання до бази даних. І якщо ви переплутали запитання, ви отримуєте або зайвий запит, або зайву складність, або неочікувану помилку.

2. save: «записати» — означає вставити або оновити

Коли ви вперше бачите save, рука сама тягнеться використовувати його як універсальний молоток. У світі новачка-розробника все виглядає просто: «я щось змінив — отже, треба викликати save». Загалом, для сьогоднішнього рівня це навіть непогана звичка, тому що робить запис у БД явним. Але важливо розуміти, що save — це операція запису, і вона може означати дві різні речі.

На дуже практичному рівні save відповідає на запитання: «зроби так, щоб цей стан сутності опинився в базі даних». Для нової сутності це перетворюється на INSERT, а для наявної — на оновлення (UPDATE), але зовнішній контракт один і той самий: ви викликаєте save, і Spring Data JPA бере на себе взаємодію з JPA/Hibernate.

save для нової сутності: зручно отримати id

Найчастіший «перший» сценарій — створення категорії або товару. Сутність нова, id ще немає, а після збереження він з’явиться.

import com.example.shopdatajpa.catalog.entity.Category;

// Створюємо нову сутність: вона ще не пов’язана із записом у БД
Category category = new Category();
category.setCode("electronics");
category.setName("Електроніка");

// У реальному сервісі тут буде categoryRepository.save(category)
// До збереження id зазвичай відсутній (ще не згенерований базою)
System.out.println(category.getId()); // null (до збереження)

У реальному коді ми зберігаємо через репозиторій, а потім можемо використовувати id, який буде присвоєний у БД. Якщо ви зберігаєте й надалі хочете працювати саме із збереженим об’єктом, зручно прийняти результат save у змінну.

import com.example.shopdatajpa.catalog.entity.Category;

// Заповнюємо сутність як звичайний об’єкт у пам’яті
Category category = new Category();
category.setCode("books");
category.setName("Книги");

// Виклик save ініціює запис у БД (INSERT для нової сутності)
Category saved = categoryRepository.save(category);

// У збереженої сутності вже є id, який присвоєно на боці БД/ORM
System.out.println(saved.getId()); // наприклад: 1

Тут важливо не перетворювати це на правило «завжди зберігай у змінну», але пам’ятати: save повертає результат запису, і це часто корисно.

save для оновлення: найчастіше ви оновлюєте «після читання»

У навчальному проєкті найзрозуміліший патерн оновлення виглядає так: спочатку читаємо сутність, змінюємо поля, потім зберігаємо.

import com.example.shopdatajpa.catalog.entity.Category;

// 1) Спочатку читаємо наявну сутність із БД
Category category = categoryRepository.findById(1L).orElseThrow();

// 2) Змінюємо потрібні поля в об’єкті
category.setName("Книги та комікси");

// 3) Явно фіксуємо зміни записом (зазвичай UPDATE для наявного запису)
categoryRepository.save(category);

Так, тут ми вже використали findById і Optional, до них ми зараз перейдемо. А поки зафіксуємо головну думку: save — це про запис, і якщо вам потрібно «просто прочитати», save не є способом читання (навіть якщо дуже хочеться).

3. findById і Optional: чесне читання

У програмуванні є два типи «немає значення». Перший — коли це помилка («щось зламалося»). Другий — коли це нормальна ситуація («значення просто немає»). У шарі доступу до даних відсутність запису за id зазвичай належить до другого типу: користувач міг передати неіснуючий id, запис могли видалити, ви могли дивитися на порожню базу в dev-оточенні. Тому findById повертає не Product, а Optional<Product>.

findById відповідає на пряме й чесне запитання: «чи є сутність із таким id, і якщо так — дай її». Якщо сутності немає, метод не зобов’язаний «падати», тому що це звичайний сценарій. Замість цього він повертає порожній Optional.

Найпростіший варіант: повернути Optional далі

Іноді сервісу й справді зручно повернути Optional коду, що викликає, — це чесно й знімає частину рішень із поточного шару.

import com.example.shopdatajpa.catalog.entity.Product;
import java.util.Optional;

public Optional<Product> findProduct(Long id) {
    // Повертаємо Optional як частину контракту: товару може не бути
    return productRepository.findById(id);
}

Цей варіант хороший тим, що метод одразу каже: «товару може не бути». Поганий він тільки в одному випадку: якщо ваш наступний код усе одно хоче вважати відсутність помилкою, ви просто перекладаєте рішення на іншу людину (або на себе ж через п’ять хвилин).

Частий варіант у сервісі: «немає сутності — отже, це помилка сценарію»

Якщо для конкретного сценарію використання відсутність запису означає, що сценарій не може продовжуватися, ви перетворюєте Optional на виняток. Тут важливо не переборщити з філософією: ми не обговорюємо зараз побудову помилок для REST, ми просто показуємо базову реакцію сервісу.

import com.example.shopdatajpa.catalog.entity.Product;

public Product getProductOrThrow(Long id) {
    // Шукаємо товар за id; якщо його немає — явно перетворюємо це на помилку сценарію
    return productRepository.findById(id)
            .orElseThrow(() -> new IllegalArgumentException("Товар не знайдено: " + id));
}

Такий код читається дуже просто: «спробуй знайти, якщо не знайшов — це не той стан, з яким ми хочемо жити».

Optional.get() — це як ходити по квартирі вночі із заплющеними очима

Технічно Optional має метод get. І технічно він навіть іноді працює. Але якщо значення відсутнє — ви отримаєте NoSuchElementException, і це буде максимально марна помилка, тому що ви самі обрали «впасти без пояснення».

import com.example.shopdatajpa.catalog.entity.Product;
import java.util.Optional;

Optional<Product> productOpt = productRepository.findById(10L);

// Небезпечний варіант: якщо Optional порожній, упадемо з NoSuchElementException без зрозумілого контексту
Product product = productOpt.get(); // може впасти NoSuchElementException

Нормальні «безпечні» варіанти — це orElseThrow(...), orElse(...) (якщо у вас є розумне значення за замовчуванням) або перевірка через isPresent() / isEmpty().

4. existsById: запитання «чи існує запис?»

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

existsById відповідає на інше запитання: «чи є запис із таким id, так чи ні?» Він не обіцяє вам сутність, не приносить самі дані, а повертає тільки boolean. Це корисно, коли вам справді потрібна лише логічна відповідь.

Доречний приклад: «покажи, що категорія взагалі існує»

У сервісі може бути метод, який потрібен для простого рішення: наприклад, ми хочемо заборонити дію, якщо категорії немає, але саму категорію нам не потрібно завантажувати.

public boolean categoryExists(Long categoryId) {
    // Тут нам потрібен тільки факт існування, без завантаження сутності цілком
    return categoryRepository.existsById(categoryId);
}

Якщо ви повертаєте boolean, сценарій зазвичай звучить як «дозволено/заборонено», «є/немає», «можна/не можна». І existsById сюди лягає ідеально.

Невдалий патерн: existsById + findById «для надійності»

Плавно і без списків: це погана ідея, якщо вам усе одно потрібна сутність. Тому що ви спочатку ставите запитання «чи є?», а потім ставите запитання «дай сутність». База даних при цьому не стає щасливішою. Вона просто виконує два запити.

import com.example.shopdatajpa.catalog.entity.Product;

public Product loadProductBad(Long id) {
    // Перший запит: перевіряємо існування (boolean)
    if (!productRepository.existsById(id)) {
        throw new IllegalArgumentException("Товар не знайдено: " + id);
    }

    // Другий запит: усе одно завантажуємо сутність — разом два звернення до БД замість одного
    return productRepository.findById(id).orElseThrow(); // другий запит
}

Якщо вам потрібна сутність — у більшості випадків ви одразу використовуєте findById і обробляєте Optional.

5. getReferenceById: сутність, яка може «стрельнути» пізніше

Метод getReferenceById звучить дружньо, але поводиться хитро. Він як людина, яка каже: «Так-так, я в темі», а потім виявляється, що розбереться в цьому трохи пізніше. Цей метод відповідає не на запитання «дай мені сутність», а на запитання: «дай мені об’єкт-посилання на сутність із таким id».

Практично це корисно в ситуаціях, де вам потрібне саме посилання на вже наявну сутність за відомим id, а не повний знімок її полів просто зараз. Одній частині моделі іноді достатньо самого факту «ось посилання на сутність №10». Для звичайного читання за id стандартним варіантом усе одно залишається findById: getReferenceById цінний саме як посилання, а не як «швидкий пошук».

Головна особливість у тому, що це посилання не зобов’язане негайно ходити в базу, щоб завантажити всі поля. За змістом ви отримуєте об’єкт, який представляє сутність, і читання реальних даних може статися пізніше, коли ви почнете використовувати поля. Звідси й головна пастка: якщо запису в БД немає, помилка може проявитися не в момент виклику getReferenceById, а пізніше.

Найпростіше спостереження: «посилання отримав, але даних ще не бачив»

Покажемо це максимально акуратно, без екскурсії у внутрішню реалізацію. У вас є id, і ви отримуєте посилання:

import com.example.shopdatajpa.catalog.entity.Product;

// Отримуємо "посилання" на сутність: Hibernate може не робити SELECT прямо зараз
Product ref = productRepository.getReferenceById(10L);

// Id зазвичай відомий одразу, тому його можна прочитати без звернення до бази
System.out.println(ref.getId()); // 10 (id відомий одразу)

Зміст прикладу не в тому, що System.out.println — це «правильний продакшен-логер» (ні), а в тому, що id у посиланні зазвичай доступний одразу. А от поля на кшталт name уже можуть потребувати звернення до БД, тому що їх треба десь узяти.

getReferenceById не можна вважати заміною findById

Якщо id може бути невалідним, findById дає вам «чесний контракт»: або сутність є, або немає. Із getReferenceById ви ніби берете папірець із номером і кажете: «принесіть мені замовлення №10», але не перевіряєте, чи є воно в системі. Іноді це нормально, якщо ви впевнені, що замовлення є. Іноді — жахливо, якщо ви не впевнені.

Щоб підкреслити пастку, наведемо приклад доступу до поля, який може закінчитися винятком, якщо сутності в базі немає:

import com.example.shopdatajpa.catalog.entity.Product;

// Посилання буде створено навіть для неіснуючого id
Product ref = productRepository.getReferenceById(999_999L);

// При першому доступі до даних (не до id) ORM може спробувати завантажити сутність і "стрельнути" помилкою
// ref.getName(); // під час звернення до даних може статися помилка, якщо запису немає

Ми спеціально залишили рядок закоментованим, тому що зараз нам важливіше зрозуміти контракт, ніж влаштовувати феєрверк винятків.

6. Швидка шпаргалка: який метод ставить яке запитання

Коли ви пишете сервісний метод, зручно на секунду зупинитися і «перекласти» код на людську мову. Таблиця нижче — не для зазубрювання, а для швидкої самоперевірки: чи справді ви ставите базі те запитання, яке хочете поставити.

Якщо ви триматимете цю таблицю в голові, то перестанете робити багато поширених помилок автоматично. А якщо ще й почнете промовляти собі «запитання» перед написанням коду — ви раптом відчуєте, що шар доступу до даних став спокійнішим місцем для життя.

7. Як ці методи складаються в сервісний API

Коли сервіс починає говорити мовою каталогу, він не вигадує нові операції доступу до даних. Він просто бере вже зрозумілі запитання до сховища і дає їм доменні назви. Тому перед складанням CatalogService корисно один раз побачити цю відповідність цілком.

createProduct(...)

Із таких зв’язків і складається нормальний сервісний API. Спочатку обираємо чесне запитання до сховища, а вже потім називаємо сервісний метод за змістом сценарію. Тоді сервіс залишається зрозумілим, а репозиторій не перетворюється на мішок випадкових викликів.

8. Типові помилки під час роботи з методами за id

Помилки в API репозиторія зазвичай не виглядають як «червона лампа» одразу. Вони часто проявляються як зайвий запит, дивна точка падіння або як код, який неможливо читати без вгадування, що автор мав на увазі. Тому корисно заздалегідь побачити найпопулярніші граблі й пройти повз них, не наступаючи з розгону.

Помилка №1: findById(...).get() без перевірки.
Це класика початківця Java-розробника: «ну я ж знаю, що запис є». Іноді ви справді знаєте. Але код від цього не стає надійнішим — він стає крихким. Якщо запис зникне або id буде неправильним, ви отримаєте виняток без змісту й контексту. Набагато чесніше або повернути Optional вище, або використати orElseThrow(...) із нормальним повідомленням.

Помилка №2: робити existsById, а потім усе одно findById.
Такий код виглядає «акуратно», але фактично ставить базі два запитання: «чи є?» і «дай». Якщо вам потрібна сутність — одразу використовуйте findById і обробіть Optional. existsById залишайте для сценаріїв, де справді потрібен тільки boolean.

Помилка №3: сприймати save як універсальну кнопку “зроби добре”.
save — це запис. Якщо ви намагаєтеся «прочитати через save» (наприклад, сподіваючись, що save якось перевірить існування і поверне вам сутність), ви просто плутаєте обов’язки методів. У кращому разі ви отримаєте зайвий запис, у гіршому — складну для налагодження ситуацію, де дані «чомусь змінилися».

Помилка №4: вважати, що getReferenceById — це просто “швидший findById”.
getReferenceById повертає посилання, і це інший контракт. Якщо id не існує, помилка може з’явитися пізніше — у місці, яке ви не пов’язуєте з читанням із бази. Якщо ви не впевнені в коректності id, то вам потрібен findById і Optional, а не «посилання на удачу».

Помилка №5: ігнорувати повернене значення save, коли далі потрібен результат запису.
Іноді розробник робить repository.save(entity); і продовжує використовувати старе посилання на об’єкт, очікуючи, що все вже «оновилося». У більшості простих випадків це спрацює, але звичка все одно небезпечна: ви втрачаєте явність. Якщо вам важливий id або подальша робота із збереженим об’єктом, краще прийняти результат save у змінну й використовувати його, щоб код був прозорим.