@OneToOne i model dziedziny

1. Niezmiennik: ograniczenie 1:1

Gdy po raz pierwszy widzisz @OneToOne, pojawia się silna pokusa, żeby odebrać go jako „no okej, jeszcze jedna adnotacja do kolekcji". Ale @OneToOne to nie dekoracja kodu, a deklaracja o twardym ograniczeniu dziedziny przedmiotowej. I jeśli skłamiesz w tej deklaracji, baza danych potem bardzo przekonująco wyjaśni, kto tu jest głównym architektem (spoiler: nie ty).

Kluczowa myśl jest taka: w prawdziwym projekcie prawie zawsze jest różnica między zdaniami „teraz produkt ma jeden obiekt szczegółów" i „produkt zasadniczo nie może mieć dwóch obiektów szczegółów". Pierwsze zdanie opisuje sytuację „na razie tak wyszło", a drugie — niezmiennik, czyli regułę, którą system musi chronić. W JPA @OneToOne ma sens tylko w drugim przypadku, bo nie tylko powiązujesz dwie klasy — utrwalasz, że model nie dopuszcza wielości.

Spróbujmy przez banalną analogię (bez niej trudno). Wyobraź sobie: człowiek może mieć paszport. Zazwyczaj jeden. Ale „zazwyczaj" to nie niezmiennik. W różnych krajach, sytuacjach, z różnymi dokumentami i statusami — może być inaczej. Jeśli budujesz system, gdzie paszport jest ściśle jeden, musisz wytłumaczyć dlaczego: na przykład „pracujemy tylko w jednym kraju i prowadzimy jeden aktywny paszport". Jeśli jutro pojawi się „tymczasowy dowód tożsamości", twoje „ściśle jeden" nagle stanie się kłamstwem. Z produktami i ich szczegółami — ta sama historia.

Dlatego właściwy start dla @OneToOne — to nie „gdzie postawić adnotację", a kilka uczciwych pytań do modelu:

• „Czy jeden Product może mieć kilka zestawów szczegółów (np. dla różnych języków, regionów, wersji produktu, wariantów)?"
• „Czy produkt może mieć kilka rekordów stanów magazynowych (magazyny, partie, rezerwy pod różne kanały sprzedaży)?"
• „Jeśli dziś odpowiedź brzmi «nie», to dlatego że tak jest urządzony biznes, czy dlatego że nie zdążyliśmy jeszcze skomplikować systemu?"

W naszym projekcie edukacyjnym świadomie upraszczamy domenę: jeden magazyn, jeden rekord stanu, jedna szczegółowa karta. To normalne, bo kurs nie jest o całym świecie e‑commerce, a o podstawowych mechanikach data-layer. Ale nawet w edukacyjnym uproszczeniu chcemy, żeby wybór @OneToOne wyglądał świadomie, a nie „widziałem adnotację w internecie i postawiłem".

2. One-to-one w bazie: FK + UNIQUE

Bardzo ważne jest pamiętanie: JPA żyje na bazie relacyjnej, a baza relacyjna nie wie, czym jest „referencja do obiektu". Zna tabele, kolumny i ograniczenia. Dlatego jeśli chcesz prawdziwego związku jeden-do-jednego, musi on być wyrażony w schemacie jako ograniczenie, a nie jako „umówiliśmy się w kodzie i mamy nadzieję, że nikt nie naruszy".

W modelu relacyjnym „jeden-do-jednego" prawie zawsze jest realizowane tak: tabela obiektu podrzędnego ma klucz obcy na rodzica, i ten klucz obcy jest unikalny. Tzn. „każdy rekord szczegółów wskazuje na jeden produkt" (to FOREIGN KEY), i jednocześnie „na jeden produkt może wskazywać co najwyżej jeden rekord szczegółów" (to UNIQUE).

Można to zobaczyć na prostym szkicu SQL (teraz nie robimy migracji ani trybu produkcyjnego, ale jako model — bardzo przydatne):

create table product (
  id bigint primary key,
  sku text not null unique
);

create table product_details (
  id bigint primary key,
  -- FK mówi: "szczegóły wskazują na istniejący produkt"
  -- UNIQUE mówi: "jeden produkt nie może mieć dwóch wierszy szczegółów"
  product_id bigint not null unique references product(id),
  manufacturer text
);

Tu product_id ... references product(id) mówi: „szczegóły muszą wskazywać na istniejący produkt". A unique mówi: „w tabeli product_details nie może być dwóch wierszy z tym samym product_id". Czyli produkt naprawdę może mieć co najwyżej jeden zestaw szczegółów.

Żeby utrwalić obraz w głowie, warto wyobrazić to jako mały schemat:

erDiagram
  %% Związek 1:1 zapewniany jest nie adnotacją, a UNIQUE na FK w bazie
  PRODUCT ||--|| PRODUCT_DETAILS : "1 to 1 via unique FK"

  PRODUCT {
    bigint id PK
    text sku UK
  }

  PRODUCT_DETAILS {
    bigint id PK
    bigint product_id FK
  }

Sama adnotacja JPA @OneToOne bez unikalności w bazie — to „proszę, traktuj to jako one-to-one", ale baza mówi: „Uważam, że to po prostu klucz obcy, a ile jest wierszy — mnie wszystko jedno, jeśli nie postawiłeś ograniczenia". I baza będzie mieć rację.

W tym miejscu często rodzi się użyteczna reguła: one-to-one w schemacie — to zawsze nieco bardziej „kosztowny" i wymagający kontrakt niż się wydaje. Musisz pomyśleć o unikalności, obowiązkowości (nullable=false), o tym, kto bez kogo istnieje i jak nie dopuścisz do duplikatów. To normalne. To nie „złożoność dla złożoności", to cena uczciwego modelu.

3. Trzy sposoby przechowywania rozszerzonych danych

Częsta sytuacja w projekcie: zacząłeś od prostego Product, a potem przychodzi rzeczywistość i mówi: „A może jeszcze producenta, gwarancję, kraj pochodzenia, długi opis…". I tu można albo zamienić Product w wielotomowe dzieło (gdzie drugi tom — „Opis", trzeci — „Magazyn", czwarty — „Tagi i metafizyka"), albo ostrożnie rozdzielić odpowiedzialność.

Dla nowicjusza warto zobaczyć, że wybór nie jest binarny „albo wszystko w jednej tabeli, albo @OneToOne". Są co najmniej trzy rozsądne formaty i każdy ma swoją rolę.

Poniżej tabela pomagająca myśleć nie adnotacjami, a konsekwencjami:

Zauważ: „rzadko czytane" samo w sobie nie czyni danych kandydatem na @OneToOne. Rzadko czytane może oznaczać, że potrzebujesz ostrożniej projektować czytanie, ale to już inna rozmowa (jej dziś nie zaczynamy). Dla @OneToOne potrzebna jest domenowa przyczyna, a nie tylko „chcę zrobić ładnie".

Żeby poczuć granicę, zobaczmy „przeciążony Product" — przykład tego, jak łatwo przypadkowo wymieszać różne podsystemy (katalog i szczegóły) w jedną encję:

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import java.math.BigDecimal;

@Entity
class Product {
    @Id Long id;               // tożsamość produktu
    String sku;                // publiczny identyfikator w katalogu
    BigDecimal price;          // cena — część "rdzenia" katalogu
    String manufacturer;       // szczegóły karty (pytanie: czy to naprawdę rdzeń?)
    Integer warrantyMonths;    // szczegóły karty (często niepotrzebne w każdym scenariuszu)
}

Kod się kompiluje, JPA nie narzeka, wszystko niby działa. Ale model staje się mniej czytelny: gdzie kończy się „rdzeń katalogowy", a gdzie zaczyna „szczegółowa karta"? A co jeśli jutro gwarancja i producent będą potrzebne nie wszystkim produktom? A jeśli karta szczegółów będzie żyć według innych reguł?

A oto wariant, gdzie karta szczegółów to oddzielna encja (na razie tylko jako idea, nie jako ostateczna recepta mappingu):

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

@Entity
class Product {
    @Id Long id;                 // tożsamość produktu
    String sku;                  // pole bazowe katalogu

    @OneToOne
    ProductDetails details;      // idea: oddzielna encja dla "karty szczegółów"
}

Tak, tu wiele pytań (gdzie FK, która strona „główna", czy potrzebna nawigacja odwrotna). Ale jako sygnał modelowy to już mocniejszy: „szczegóły — oddzielna strefa danych, nie tylko trzy pola więcej".

Małe ćwiczenie, które można zrobić teraz w głowie (lub w projekcie, jeśli jest otwarty): weź Product i spróbuj podzielić pola na „rdzeń katalogowy" (to, co jest potrzebne prawie zawsze) i „szczegółowa karta" (to, co potrzebne tylko w scenariuszu „otwórz kartę produktu"). Jeśli wychodzą ci dwa różne zestawy sensów — kandydat na @OneToOne naprawdę się pojawia. Jeśli nie — możliwe, że po prostu chcesz „ładnej architektury", a biznes jeszcze tego nie potrzebuje.

4. Przypadki projektu

ProductDetails jako kandydat na @OneToOne

W naszej domenie mini‑shop ProductDetails — to właśnie „rozszerzona karta produktu". Żyje obok produktu, ale ma nieco inny sens: Product — to to, co potrzebne do katalogu i bazowej identyfikacji, a ProductDetails — to to, co potrzebne na stronie „więcej szczegółów".

Tu @OneToOne wygląda naturalnie właśnie jako niezmiennik: produkt nie ma dwóch „kart szczegółów". To nie historia „jeden rekord teraz", to właśnie „model jest tak urządzony". Jeśli jutro pojawią się różne wersje opisów, różne języki lub różne warianty — tak, model się zmieni. Ale teraz utrwalamy jeden zestaw szczegółów na jeden produkt, bo to uczciwe uproszczenie i dobry przykład edukacyjny.

Ważne też to, że wyniesienie szczegółów do oddzielnej encji pomaga architektonicznie: Product pozostaje kompaktowy i „katalogowy", a ProductDetails staje się oddzielną częścią modelu persistence. Nawet jeśli na razie nie myślisz o oddzielnych serwisach, „granica odpowiedzialności" w danych staje się widoczna.

Z punktu widzenia kontraktu mappingu chcemy, żeby „szczegóły nie istniały bez produktu" i żeby „produkt nie miał dwóch zestawów szczegółów". Zazwyczaj wyraża się to przez klucz obcy na Product i unikalność:

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

@Entity
class ProductDetails {
    @Id Long id; // tożsamość "karty szczegółów" (strategię generowania tu pomijamy)

    @OneToOne
    @JoinColumn(
        name = "product_id",
        unique = true,      // zabraniamy dwóch wierszy ProductDetails na jeden Product
        nullable = false    // zabraniamy "karty bez produktu"
    )
    Product product;        // referencja do produktu; FK fizycznie leży w tabeli ProductDetails
}

Zwróć uwagę: nawet jeśli jeszcze nie myślisz o owning side i mappedBy (to będzie oddzielna lektura), idea unikalnego FK już pokazuje studentowi, że „jeden-do-jednego" — to nie poczucie, a ograniczenie.

I jeszcze jeden ważny moment: ProductDetails — to nie „po prostu wynieśliśmy pola". To oddzielna encja, bo ma oddzielny sens. Tam mogą pojawiać się własne reguły walidacji, własne zmiany, własne scenariusze życia. Dziś wygląda to jak kilka linii, a jutro — jak naprawdę oddzielna część modelu.

StockItem jako kandydat na @OneToOne

Ze stanami magazynowymi jest typowy podchwyt nowicjusza: „To tylko dwie liczby, po co oddzielna encja? Wrzućmy availableQuantity wprost do Product". I na małym demo to naprawdę wygląda logicznie. Ale domenowo StockItem — to nie tylko dwie liczby. To oddzielna strefa danych, która należy do podsystemu inventory, zmienia się często i zazwyczaj ma własne reguły.

W naszym projekcie utrwalamy uproszczenie: „jeden magazyn → jeden rekord stanu na produkt". To właśnie jest powód dla @OneToOne. Nie mówimy „produkt ma teraz jeden rekord stanu", mówimy „w naszym modelu celowo jest jeden rekord stanu". Jak tylko pojawią się magazyny — model zacznie się zmieniać. Ale teraz @OneToOne uczciwie odzwierciedla edukacyjną dziedzinę.

Jest jeszcze jeden cichy, ale praktyczny argument: stany magazynowe często żyją własnym życiem. Katalog zmienia się rzadko (nazwa, cena), a stany — ciągle (rezerwacja, przyjęcie, odpisanie). Nawet jeśli na razie nie projektujesz złożonych procesów, oddzielna encja pomaga mózgowi (i kodowi) nie mieszać „opisu produktu" i „stanu magazynu".

Mini-fragment encji stanów magazynowych może wyglądać tak:

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

@Entity
class StockItem {
    @Id Long id; // tożsamość rekordu stanów

    @OneToOne
    @JoinColumn(
        name = "product_id",
        unique = true,        // jeden produkt -> maksymalnie jeden rekord stanów
        nullable = false      // stany nie mogą istnieć "same przez się"
    )
    Product product;          // do jakiego produktu należy stan

    int availableQuantity;    // dostępna ilość (uproszczone: bez rezerwacji/partii/magazynów)
}

Celowo nie dodaję tu niczego zbędnego. Sens teraz nie w ilości pól, a w tym, że to oddzielny obiekt z oddzielnym sensem. I znowu kluczowy znacznik one-to-one — unikalność product_id.

Żeby ostatecznie się nie pogubić, warto trzymać w głowie taki model:

flowchart TD
  P[Product: rdzeń katalogowy] --> D[ProductDetails: szczegółowa karta]
  P --> S[StockItem: stan magazynowy]

To nie o tym, że „związki są ładne". To o tym, że mamy trzy różne strefy danych sensu i chcemy, żeby model persistence to odzwierciedlał.

5. Oznaki stosownego @OneToOne

Najpopularniejsza pułapka @OneToOne — używanie go jako architektonicznej kosmetyki: „podzielimy encję na dwie, bo tak modnie". W rezultacie komplikujesz model, dodajesz kolejną tabelę, kolejny związek, a potem szczerze się dziwisz, dlaczego stało się trudniej czytać i zapisywać dane.

Poniżej mały schemat blokowy pomagający podjąć decyzję „na serwetce". Nie jest idealny, ale dla poziomu junior dobrze dyscyplinuje myślenie:

flowchart TD
  A[Chcemy wynieść część pól do oddzielnego obiektu] --> B{To oddzielny sens/odpowiedzialność?}
  B -- nie --> C["Raczej: zostawić w encji lub zrobić @Embeddable"]
  B -- tak --> D{Czy może być więcej niż jeden na rodzica?}
  D -- tak --> E["To już nie OneToOne (patrz OneToMany/ManyToOne)"]
  D -- nie --> F{Czy potrzebna gwarancja w bazie?}
  F -- tak --> G[OneToOne: FK + UNIQUE + jasny cykl życia]
  F -- nie --> H["Ostrożnie: to już nie 'niezmiennik', a umowa"]

Zwróć uwagę na węzeł „czy potrzebna gwarancja w bazie". Właśnie tam przebiega granica między „tak piszemy kod" a „system chroni dane". Dla @OneToOne ważne, żeby to była właśnie chroniona reguła. Inaczej zamienia się w dekoracyjny związek, który „niby 1:1, ale baza może przechowywać jak chce".

Jeśli chcesz małej praktyki bez ciężkich ćwiczeń: weź dowolną parę ze swojej domeny (na przykład CustomerOrder i „dostawa"), i spróbuj uczciwie odpowiedzieć na pytanie „czy może być więcej niż jeden?". Zamówienie może mieć kilka adresów dostawy? Zazwyczaj nie, ale może być „historia zmian adresu", może być „kilku odbiorców", może być „dostawa częściami". W tym miejscu poczujesz, że @OneToOne — to nie „jak powiązać klasy", a „jak nie skłamać modelowi".

6. Typowe błędy przy wyborze @OneToOne

Błąd nr 1: „Postawię @OneToOne, bo teraz jest jeden rekord".
Jeśli „jeden" — to po prostu bieżący stan danych, a nie reguła biznesowa, @OneToOne staje się fałszywą obietnicą. W takim przypadku bardziej uczciwe jest przyznanie, że to na razie ManyToOne/OneToMany lub w ogóle oddzielna tabela bez twardej kardynalności. @OneToOne ma sens wtedy, gdy jesteś gotów chronić regułę „nie ma więcej niż jeden".

Błąd nr 2: „Wyniosę do oddzielnej encji, bo pól jest dużo".
Ilość pól sama w sobie nie jest kryterium. Czasem wiele pól — to naprawdę rdzeń encji i wyniesienie ich tylko pogorszy czytelność. Kryterium — to oddzielny sens, oddzielna odpowiedzialność i oddzielne scenariusze życia danych. Jeśli oddzielnego sensu nie ma, najczęściej wystarczy zostawić pola w encji lub sformatować je przez @Embeddable, żeby kod był bardziej strukturalny bez komplikowania bazy.

Błąd nr 3: „Związek jest w Javie, znaczy one-to-one jest już gwarantowane".
Referencja Java nie zabrania bazie przechowywać dwóch wierszy szczegółów na jeden produkt. Gwarancja one-to-one pojawia się tylko wtedy, gdy wyrażasz ograniczenie na poziomie schematu: unikalny klucz obcy (lub inny równoważny mechanizm). Jeśli unikalności nie ma, możesz nazwać to one-to-one w kodzie, ale będzie to „one-to-many w masce".

Błąd nr 4: „Rzadko czytane — znaczy na pewno potrzebny @OneToOne".
Rzadkie czytanie to słaby argument. Może skłaniać do ostrożniejszego modelowania, ale nie dowodzi, że dane powinny być oddzielną encją. Ważne jest najpierw rozstrzygnąć kwestię kardynalności i sensu, a dopiero potem myśleć o tym, jak i kiedy to jest czytane. Inaczej łatwo dostać strukturę, która wygląda mądrze, ale nie odpowiada dziedzinie przedmiotowej.

Błąd nr 5: „Zrobię wszystko one-to-one, żeby było modułowo".
Jeśli zacząć dzielić wszystko na one-to-one „dla modułowości", wyjdzie model-frankenstein: dużo tabel, dużo związków, dużo miejsc na błąd, i zerowa korzyść dla biznesu. Dobry model jest zazwyczaj powściągliwy: one-to-one jest używany punktowo, tam gdzie naprawdę odzwierciedla ograniczenie domeny, a nie tam gdzie chcemy „ładnej architektury".