Антипаттерны связей в Product

1. Антипаттерны связей вокруг Product

Если честно, антипаттерны в связях появляются не потому, что разработчики плохие или ленивые. Они появляются потому, что JPA очень соблазнителен: хочется «просто добавить поле-ссылку», «просто сделать двустороннее, вдруг пригодится», «просто поставить EAGER, чтобы точно всё было под рукой». И внезапно сущность начинает вести себя как чемодан без ручки: тащить неудобно, бросить жалко, а жить в ней становится всё тяжелее.

Product в домене мини-магазина — идеальная мишень для этих ошибок. Почему? Потому что это «центральная» сущность каталога: к ней хочется прицепить категорию, детали, остатки, теги, позиции заказов, отчёты, настроение разработчика и ещё пару «полезных» ссылок. В итоге Product рискует стать не моделью товара, а моделью всего мира, включая соседний подъезд.

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

Чтобы было проще держать это в голове, вот маленькая таблица, которая заменяет тысячу «ну вроде нормально же»:

2. Антипаттерн: giant object graph

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

Посмотрите на типичную картину giant object graph (упрощённо). Это не «плохой код» в смысле компиляции — это плохой код в смысле жизни:

flowchart TD
    P[Product] --> C[Category]
    P --> D[ProductDetails]
    P --> S[StockItem]
    P --> T[Tag]
    P --> OI[OrderItem]
    OI --> O[CustomerOrder]
    OI --> P
    T --> P
    C --> P

Если вы сделали много двусторонности, граф начинает замыкаться в петли, и сущность превращается в нечто, что невозможно безопасно «потрогать». Проблема даже не в том, что это «плохо по учебнику», а в том, что вы теряете контроль над тем, что реально будет загружаться и какие объекты будут жить в памяти.

Вот иллюстрация «плохого Product». Я специально делаю её короткой, но достаточно показательной:

import jakarta.persistence.*;
import java.util.HashSet;
import java.util.Set;

@Entity
public class Product {

    // Антипаттерн: EAGER на "естественной" связи -> любой запрос за Product тянет Category
    @ManyToOne(fetch = FetchType.EAGER)
    private Category category;

    // Антипаттерн: EAGER на one-to-one -> даже если остатки не нужны, они окажутся в памяти
    @OneToOne(fetch = FetchType.EAGER)
    private StockItem stockItem;

    // Антипаттерн: EAGER на коллекции -> риск "дорогого чтения" и непредсказуемого числа запросов
    @ManyToMany(fetch = FetchType.EAGER)
    private Set<Tag> tags = new HashSet<>();
}

Снаружи это выглядит как «удобно». На практике это означает: любое чтение Product начинает иметь непредсказуемую цену. Даже если конкретному методу нужен только name или price, вы всё равно тащите категорию, остатки и теги — просто потому что когда-то кто-то хотел «чтобы было под рукой».

В реальном проекте после такого кода начинается «весёлый» этап: вы пытаетесь оптимизировать запросы (пока мы это ещё не делаем в этом модуле), потом начинаете бояться менять связи, потом начинаете писать костыли «на всякий случай», а потом у вас появляются фразы в код-ревью уровня «не трогай это, оно работает». Это как раз тот момент, когда вместо инженерии начинается шаманство, а шаманство с базой данных — вещь дорогая.

3. Антипаттерн: случайная двусторонность

Двунаправленные связи в JPA — не зло. Зло — это делать их «по привычке». Новичку очень легко думать так: «Если Product знает Tag, то Tag должен знать Product. Так симметричнее». В Java симметрия выглядит красиво. В ORM симметрия часто превращается в дополнительный повод для боли, особенно если вы не готовы поддерживать дисциплину синхронизации двух сторон.

Вот пример двусторонней связи Tag → Product, которая добавлена просто потому что «а вдруг понадобится»:

import jakarta.persistence.*;
import java.util.HashSet;
import java.util.Set;

@Entity
public class Tag {

    // Обратная сторона связи: сама по себе в БД ничего не "запишет" (это inverse side)
    // Плюс: добавляет риск циклов в логах/toString и необходимость синхронизации обеих сторон
    @ManyToMany(mappedBy = "tags")
    private Set<Product> products = new HashSet<>();
}

Вопрос не «можно ли так». Можно. Вопрос: зачем вам навигация от тега к товарам прямо сейчас? Если ответ «ну… может быть когда-нибудь», то вы вешаете на модель обязательство. Теперь вы обязаны помнить, что есть вторая сторона, что её нужно синхронизировать, что у вас появляются циклы для toString(), и что любая случайная логика «пройдусь по продуктам и по их тегам» может неожиданно вырасти в сложный обход графа.

И здесь важно: даже если мы вообще не делаем web-layer и не сериализуем entity в JSON, циклы всё равно опасны. Они «всплывают» в логировании, в отладке, в toString(), в IDE, в случайных мапперах, в тестах, и, конечно же, в голове разработчика. Сущность, которую страшно вывести в лог — это сущность, которой вы уже не управляете.

Вспомните лекции про equals/hashCode/toString: если вы по незнанию включите в toString() поля-связи, то достаточно одной двусторонней связи — и у вас будет бесконечная рекурсия. Это тот редкий момент, когда программа буквально говорит: «Я пошёл по кругу, как и ты».

4. Антипаттерн: @ManyToMany вместо сущности-связки

@ManyToMany в учебном проекте — полезный инструмент, но он должен оставаться «controlled bonus». Проблема начинается, когда мы начинаем использовать его как универсальный шаблон для любых «много ко многим». В реальных проектах почти всегда наступает момент, когда у самой связи появляются свойства. Например, «кто назначил тег», «откуда тег пришёл», «приоритет тега», «время назначения».

Как только вы произнесли фразу «у связи есть поле…» — у вас больше нет “просто @ManyToMany”. Потому что join-table перестаёт быть «технической таблицей с двумя id», а становится носителем смысла.

Вот пример, который отлично показывает этот переломный момент:

import jakarta.persistence.*;

@Entity
public class ProductTagAssignment {

    // Сущность-связка: мы явно моделируем "назначение тега товару"
    @ManyToOne(optional = false)
    private Product product;

    @ManyToOne(optional = false)
    private Tag tag;

    // Поле, которое превращает связь в "содержательную" (и убивает идею простого ManyToMany)
    private String source; // например: "MANUAL", "IMPORT", "AI"
}

С этого момента ProductTagAssignment — это не «лишняя сущность ради сложности», а нормальная доменная вещь: назначение тега товару с источником назначения. И вот тут @ManyToMany перестаёт быть хорошим решением, потому что он просто не выражает смысл.

В нашем mini-shop курсе мы не обязаны уходить в эту глубину. Более того, по плану курса мы специально держим Tag в роли второстепенной фичи, чтобы проект не превратился в «tagging platform». Но вы должны видеть красную линию: если связь стала содержательной, ей нужен свой класс.

5. Антипаттерн: забыли вторую сторону связи

Есть очень типичная ошибка, которая выглядит настолько невинно, что за неё обидно: вы добавляете элемент в коллекцию и искренне думаете, что «всё, связь установлена». А потом выясняется, что вторая сторона вообще не в курсе, и объектная модель у вас противоречивая. Это как написать друзьям «я в отпуске», но забыть уйти в отпуск.

Самый короткий пример — тот, который кажется правильным:

// Меняем только коллекцию на одной стороне.
// Если связь двусторонняя, то "вторая сторона" об этом не узнает сама.
product.getTags().add(tag);

Если связь двусторонняя, то этот код меняет только одну сторону. Вторая сторона (tag.getProducts()) остаётся в старом состоянии. Более того, если вы изменили только inverse side (ту, где mappedBy), JPA может вообще не сделать нужных изменений в БД, потому что в базу пишет owning side. А owning side — не «главнее по философии», а буквально «там находится управление FK / join table».

Нормальная дисциплина для двусторонней связи — helper-методы. Да, это немного «рутины», но это та рутина, которая покупает вам предсказуемость.

Вот компактный вариант (и да, он выглядит скучнее, чем “просто add”, зато он честнее):

import java.util.Objects;

public void addTag(Tag tag) {
    // Защищаемся от "тихих" NPE и мусорных данных в коллекции
    Objects.requireNonNull(tag, "tag must not be null");

    // Обновляем owning side (например, Product.tags)
    tags.add(tag);

    // Синхронизируем обратную сторону, чтобы объектная модель не противоречила сама себе
    tag.getProducts().add(this);
}

Если вы выбрали двустороннюю навигацию, вы обязаны быть последовательными: не «иногда helper, иногда руками». Иначе вы гарантированно получите ситуацию, когда в памяти одно, а в базе другое, и отлаживать это вы будете долго и философски.

Здесь есть и хорошая новость: если обратная навигация не нужна, вы можете сделать связь однонаправленной. Тогда вам не нужно синхронизировать две стороны, и модель становится проще. Для Product -> Tag это часто идеальный старт.

6. Антипаттерн: EAGER как универсальная таблетка

FetchType.EAGER обычно появляется в проекте как реакция на боль. У вас где-то не хватает данных, вы получаете LazyInitializationException (или просто «что-то не загрузилось»), и мысль звучит так: «Ну окей, поставлю EAGER, и всё будет загружаться сразу». На короткой дистанции это даже может сработать. На длинной — вы просто меняете одну боль на другую: вместо «иногда не загрузилось» получаете «всегда читаем слишком много».

Важно понять: EAGER не означает «один хороший JOIN и всё». Иногда ORM действительно сделает join. Иногда сделает отдельные запросы. Иногда, когда связей много, получится смесь. Но самое неприятное — вы перестаёте контролировать цену чтения на уровне use case. Любой код, который просит Product, внезапно платит за всё сразу.

Посмотрите на этот метод — он просит только имя:

public String loadProductName(Long id) {
    // Даже если нам нужно только имя, репозиторий вернёт сущность "как она замапплена":
    // при EAGER-связях вы заплатите за весь граф.
    Product product = productRepository.findById(id).orElseThrow();
    return product.getName();
}

Если в Product всё размечено как EAGER, то этот метод «по дороге за именем» может принести категорию, детали, теги, остатки. Это как зайти в магазин за хлебом и купить ещё диван, потому что «ну раз уж пришёл». Удивительно, но многие проекты живут именно так, а потом искренне удивляются, почему чтение стало дорогим.

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

7. Дисциплина mapping для Product

Когда мы говорим «дисциплина mapping», это не про аскетизм ради аскетизма. Это про то, чтобы сущность оставалась читаемой, предсказуемой и пригодной для роста. В учебном проекте особенно важно сформировать привычку: лучше добавить связь позже, когда появится реальный use case, чем сразу сделать “супер-универсальную модель”.

Для Product в нашем проекте можно сформулировать здравую, «земную» позицию. Мы держим в Product те связи, которые действительно помогают в сценариях каталога, и очень осторожно относимся к тому, что превращает Product в узел всех подсистем.

Хороший способ закрепить решение — описать связи как маленький контракт. Например, так:

Обратите внимание на формулировки: это не «единственно правильный вариант во вселенной», это учебный инженерный default, который помогает не сломать проект ранними решениями.

8. Референсный mapping для Product

Сейчас соберём тот вариант Product, который стоит держать в голове как опорный. В обязательной части модели здесь остаются Product -> Category, двунаправленный Product <-> ProductDetails и однонаправленный StockItem -> Product. Tag полезен как лёгкая классификация, но не обязателен для ядра каталога. Я не буду показывать полный класс Product со всеми полями, потому что нам важны именно связи и дисциплина. Смысл в том, чтобы вы могли сравнить: «вот так выглядит Product-ёлка» и «вот так выглядит Product, с которым можно жить».

Product → Category и ProductDetails

Начнём с того, что Category действительно нужна в Product. Это нормальная часть каталога, и связь тут по делу.

import jakarta.persistence.*;

@Entity
public class Product {

    // Стартуем с LAZY: не платим за категорию, если use case просит только поля Product
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    private Category category;

    // Обратная сторона one-to-one: колонка FK будет в таблице ProductDetails
    @OneToOne(mappedBy = "product", fetch = FetchType.LAZY)
    private ProductDetails details;
}

Обратите внимание: details — обратная сторона. Владелец связи (и место @JoinColumn) — в ProductDetails, потому что детальная карточка не имеет смысла без товара. Это соответствует нашей предметной модели.

Владеющая сторона ProductDetails

Вот минимальный фрагмент ProductDetails, где видна owning side и ограничение «строго один к одному» через unique = true.

import jakarta.persistence.*;

@Entity
public class ProductDetails {

    // Owning side: именно здесь FK-колонка product_id и именно она управляет связью в БД
    @OneToOne(optional = false)
    @JoinColumn(name = "product_id", unique = true, nullable = false)
    private Product product;
}

Именно этот кусок делает one-to-one «частью схемы», а не просто договорённостью. Если вы забудете unique = true, то на уровне базы вы больше не гарантируете «одни детали на один товар», и тогда @OneToOne в коде становится красивой сказкой без морали.

StockItem как отдельная подсистема

Остатки — это inventory-фича. Да, StockItem связан с Product. Но это не значит, что Product обязан держать ссылку на StockItem прямо сейчас. Если вы добавите её слишком рано, catalog станет зависеть от inventory на уровне модели, а это ускоряет превращение Product в «всё про всё».

Начните с однонаправленного StockItem -> Product:

import jakarta.persistence.*;

@Entity
public class StockItem {

    // Однонаправленная связь: inventory знает про catalog, но catalog не обязан знать про inventory
    // Плюс: в БД гарантируем "ровно один остаток на один продукт" через unique
    @OneToOne(optional = false)
    @JoinColumn(name = "product_id", unique = true, nullable = false)
    private Product product;
}

Если позже окажется, что вам нужна навигация product.getStockItem() (и это будет реальный use case, а не «мне так удобнее в дебаге»), вы добавите обратную сторону mappedBy = "product" в Product. Но пока это можно не делать, и это — отличный пример дисциплины.

Tag и @ManyToMany

Если мы всё же добавляем Tag как бонус, то самый «здоровый» старт — Product знает теги, а тег не обязан знать все товары. Так вы избегаете лишней двусторонности и необходимости синхронизации.

import jakarta.persistence.*;
import java.util.HashSet;
import java.util.Set;

@Entity
public class Product {

    // Однонаправленный ManyToMany: Product -> Tag.
    // Так мы не обязаны поддерживать "обратную коллекцию" в Tag и ловить циклы.
    @ManyToMany
    @JoinTable(
        name = "product_tag",
        joinColumns = @JoinColumn(name = "product_id"),
        inverseJoinColumns = @JoinColumn(name = "tag_id")
    )
    private Set<Tag> tags = new HashSet<>();
}

И да, даже в однонаправленном варианте полезно прятать работу с коллекцией за маленькими методами. Не потому что «так по SOLID», а потому что вы можете контролировать null, дубликаты и будущее поведение.

import java.util.Objects;

public void addTag(Tag tag) {
    // Минимальная защита: не кладём null в коллекцию, чтобы не ловить сюрпризы в будущем коде
    Objects.requireNonNull(tag, "tag must not be null");

    // Добавление в Set само защищает от дублей, но смысл "входной точки" остаётся: единое место поведения
    tags.add(tag);
}

9. Типичные ошибки при борьбе с антипаттернами связей

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

Ошибка №1: превращать Product в хаб всех подсистем.
Новичок видит центральную сущность и начинает добавлять в неё ссылки на всё, что связано с товаром: остатки, заказы, теги, отчёты, «историю просмотров» (ну мало ли). В итоге Product перестаёт быть частью каталога и становится моделью вселенной. Лечится это скучно: добавляйте навигацию только под реальный use case, и не стесняйтесь держать часть связей однонаправленными.

Ошибка №2: двусторонность «ради симметрии».
Двунаправленная связь должна появляться потому, что вам реально нужна навигация в обе стороны. Если вы добавили её «на всякий случай», вы создали обязательство по синхронизации и риск циклов, но не получили ценности. В учебном проекте лучше быть прагматиком: если обратная сторона не используется — её нет.

Ошибка №3: менять inverse side и ожидать, что база всё поймёт.
Когда студент видит mappedBy, он часто воспринимает его как «ещё один способ связать», а не как «эта сторона не владеет связью». В результате он добавляет элемент в коллекцию на обратной стороне и удивляется, что в базе ничего не изменилось. Правило простое: меняем связь через owning side или через helper-методы, которые гарантируют корректность обеих сторон.

Ошибка №4: лечить всё FetchType.EAGER.
Это одна из самых дорогих привычек. Она появляется из желания «чтобы точно всё было доступно» и часто маскирует отсутствие дисциплины в границах и чтении. В нашем модуле мы ещё не управляем чтением на уровне запросов, поэтому дисциплина в mapping — это ваш основной инструмент контроля. Начинайте с LAZY, и не превращайте каждое чтение Product в оплату всего графа данных.

Ошибка №5: использовать @ManyToMany как “главный паттерн связей”.
@ManyToMany полезен, но он капризный в эволюции. Как только у связи появляются собственные поля или правила, вам нужна сущность-связка. Если держать это в голове, Tag останется приятным бонусом, а не причиной архитектурной боли.