@OneToMany и mappedBy

1. Роль @OneToMany рядом с @ManyToOne

Когда Product уже знает свою Category через @ManyToOne, у новичков почти всегда возникает очень человеческое желание: «Окей, товар знает свою категорию. А можно наоборот — взять категорию и получить список её товаров?». Это желание не от лени, а от нормального объектного мышления: в Java мы привыкли, что если у чего-то есть “дети”, то это выглядит как коллекция.

Представьте сервис каталога. Вы загрузили категорию Coffee и хотите вывести на экран (или хотя бы в лог) все товары в этой категории. С точки зрения домена это естественный вопрос: категория как справочник «содержит» набор товаров, а не является просто одиночной строкой в таблице.

Конечно, можно жить и без коллекции в сущности. Вы всегда можете сделать запрос «дай все товары, у которых category_id = ?» и получить список. Но тогда вы сознательно отказываетесь от части удобства объектной модели: у вас будет объект Category, который «по смыслу» связан с товарами, но в коде это никак не выражено. @OneToMany как раз и позволяет выразить эту навигацию: от родителя к детям.

И здесь важно не попасть в ловушку ожиданий. @OneToMany — это не магическое «создай вторую связь в базе». Это скорее способ сказать ORM: «Я хочу иметь в Java-объекте коллекцию, которая соответствует уже существующей связи через внешний ключ». В этой фразе ключевые слова — уже существующей.

2. Как хранится связь: один FK и запросы

Если смотреть глазами базы данных, то коллекция products внутри категории — это не отдельная колонка и не отдельный механизм хранения. В таблице category нет поля products, и это нормально: реляционная модель не хранит «списки ссылок» внутри строки. Она хранит строки, ключи и связи через ключи.

Связь «категория — товары» в нашем mini-shop почти всегда будет выглядеть так: таблица product содержит внешний ключ category_id, который ссылается на category(id). То есть «ребёнок» хранит ссылку на «родителя». Примерно так (упрощённо):

erDiagram
  CATEGORY ||--o{ PRODUCT : contains

  CATEGORY {
    bigint id PK
    varchar code
    varchar name
  }

  PRODUCT {
    bigint id PK
    varchar sku
    varchar name
    bigint category_id FK
  }

Если вы хотите получить товары категории, база данных не «достаёт их из колонки», а выполняет запрос. Самый прямой вариант выглядит так:

-- Получаем товары конкретной категории (пример: id = 10)
SELECT p.id, p.sku, p.name
FROM product p
-- category_id — внешний ключ на category(id)
WHERE p.category_id = 10;

А если вам нужно вывести категории вместе с их товарами (например, админский экран), вы вообще легко приходите к JOIN:

-- JOIN вернёт несколько строк (по одной на каждый товар в категории)
SELECT c.id AS category_id, c.name AS category_name,
       p.id AS product_id,  p.name AS product_name
FROM category c
JOIN product p ON p.category_id = c.id
WHERE c.id = 10;

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

Поэтому когда мы добавляем @OneToMany в JPA, мы делаем не «вторую связь», а добавляем удобную навигацию в объектной модели, которая будет опираться на тот же самый FK. И чтобы Hibernate это понял, ему нужно явно объяснить: «эта коллекция — отражение связи, которая уже описана на стороне товара». Именно этим и занимается mappedBy.

3. Двусторонний маппинг: @ManyToOne + @OneToMany

Когда мы хотим навигацию в обе стороны, у нас появляется двусторонняя связь (bidirectional association). В ней будут два поля:

1. Product.category — ссылка на родителя (@ManyToOne)
2. Category.products — коллекция детей (@OneToMany)

Но физически в базе, напомню, всё равно один FK.

В нашем проекте минимальная версия выглядит так. Сначала «детская» сторона — она у нас уже была в прошлой лекции, но я покажу её в максимально компактном виде, чтобы было видно поле, на которое мы будем ссылаться через mappedBy.

import jakarta.persistence.*;

@Entity // Сущность JPA (обычно будет отображаться на таблицу product)
public class Product {

    @ManyToOne // Много товаров могут ссылаться на одну категорию
    @JoinColumn(name = "category_id") // FK-колонка в таблице product
    private Category category;
}

Теперь добавляем «родительскую» коллекцию. И вот здесь ключевой момент — mappedBy.

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;

@Entity // Сущность JPA (обычно будет отображаться на таблицу category)
public class Category {

    @OneToMany(mappedBy = "category") // "category" — имя поля в Product, а не имя колонки
    private List<Product> products = new ArrayList<>(); // Инициализируем, чтобы не ловить NPE
}

Фраза mappedBy = "category" читается так: «Эта коллекция products маппится (то есть соответствует) полю category на другой стороне связи».

Обратите внимание на две очень важные детали, которые на удивление часто путают:

Во-первых, mappedBy указывает имя Java-поля, а не имя колонки в таблице. То есть category, а не category_id.

Во-вторых, mappedBy вообще не про SQL напрямую. Это инструкция для ORM-уровня: «Не пытайся создать отдельный механизм хранения связи для этой коллекции. Смотри на поле Product.category — оно уже определяет связь».

Абсолютно тот же паттерн будет у нас и в заказах. У позиции заказа есть ссылка на заказ (@ManyToOne), а у заказа есть коллекция позиций (@OneToMany(mappedBy = "customerOrder")).

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;

@Entity // Заказ как сущность (родитель)
public class CustomerOrder {

    @OneToMany(mappedBy = "customerOrder") // "customerOrder" — поле в OrderItem
    private List<OrderItem> items = new ArrayList<>(); // Пустой список вместо null
}

И «детская» сторона:

import jakarta.persistence.*;

@Entity // Позиция заказа (ребёнок), именно тут хранится FK на заказ
public class OrderItem {

    @ManyToOne // Много позиций могут относиться к одному заказу
    @JoinColumn(name = "customer_order_id") // FK-колонка в таблице order_item
    private CustomerOrder customerOrder;
}

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

4. mappedBy: имя поля, не колонки

mappedBy — это тот параметр, который ломает больше нервных клеток, чем кофемашина в офисе по понедельникам. Причина проста: у новичка в голове перемешиваются три уровня: Java-поля, SQL-колонки и вообще «как JPA это хранит».

Давайте упростим до почти бытового правила. В mappedBy вы пишете строку с именем поля в дочерней сущности, которое смотрит на родителя. Если вы сомневаетесь, где это поле, вы делаете очень простую вещь: открываете класс ребёнка и ищете там @ManyToOne на родителя. Имя поля рядом — это и есть mappedBy.

Например, у нас в Product:

@ManyToOne // Сторона ребёнка: тут живёт "настоящая" ссылка на родителя
private Category category; // Это имя поля и нужно указывать в mappedBy

Значит, в Category будет:

@OneToMany(mappedBy = "category") // mappedBy = имя Java-поля в Product
private List<Product> products;

Аналогично в OrderItem:

@ManyToOne // Ссылка на заказ хранится в позиции заказа
private CustomerOrder customerOrder; // Это имя поля попадёт в mappedBy

Значит, в CustomerOrder будет:

@OneToMany(mappedBy = "customerOrder") // mappedBy = имя Java-поля в OrderItem
private List<OrderItem> items;

Теперь важный антипример, который встречается почти гарантированно (как минимум один раз у каждого студента, и это нормально). Часто пишут так:

@OneToMany(mappedBy = "category_id") // ❌ неправильно: это имя колонки, а не поля
private List<Product> products;

Почему это неправильно? Потому что "category_id" — это имя колонки (в SQL-мире), а JPA просит имя поля (в Java-мире). Hibernate буквально попытается найти в Product поле category_id (а такого поля нет), и вы получите ошибку маппинга на старте приложения.

Ещё одна типичная путаница — написать имя класса:

@OneToMany(mappedBy = "Category") // ❌ неправильно: это не имя поля в ребёнке
private List<Product> products;

Это тоже не то. mappedBy — не «кто там родитель», а «через какое поле ребёнок хранит ссылку на родителя».

Если запомнить простую мантру «mappedBy = имя поля в ребёнке», большинство проблем исчезает, а жизнь становится подозрительно приятной.

5. Без mappedBy: join table и «вторая связь»

Самый полезный способ понять mappedBy — увидеть, что происходит, когда его нет. Потому что без него ORM (а точнее JPA-модель) думает так: «О, у нас есть @ManyToOne в Product и ещё @OneToMany в Category. Значит… это две отдельные связи! Надо как-то хранить вторую».

А хранить @OneToMany без mappedBy «через FK в ребёнке» JPA по умолчанию не может, потому что тогда эта @OneToMany должна была бы управлять внешним ключом на другой таблице. И самый частый дефолт, который выбирает ORM, — join table, то есть дополнительная связующая таблица.

Упрощённо это может выглядеть так:

erDiagram
  CATEGORY ||--o{ CATEGORY_PRODUCTS : links
  PRODUCT ||--o{ CATEGORY_PRODUCTS : links

  CATEGORY {
    bigint id PK
    varchar code
    varchar name
  }

  PRODUCT {
    bigint id PK
    varchar sku
    varchar name
  }

  CATEGORY_PRODUCTS {
    bigint category_id FK
    bigint product_id FK
  }

То есть вместо одного внешнего ключа product.category_id у вас внезапно появляется таблица-связка. А вы её не просили. И в домене она вам не нужна. У вас связь один-ко-многим, а не многие-ко-многим.

Поэтому mappedBy — это не “косметика для красоты”, а важная инструкция: «Вот это поле — зеркало, не создавай второй механизм хранения». Говоря человеческим языком: mappedBy экономит вам лишнюю таблицу, лишнюю сложность и лишние вопросы “а что это за чёрт”».

Здесь достаточно зафиксировать один практический вывод: коллекция с mappedBy описывает обратную навигацию и не создаёт второй способ хранить связь. FK по-прежнему живёт на стороне ребёнка, а значит коллекция — это не место записи связи, а её отражение.

6. Коллекции в entity: объявление и грабли

Когда вы добавляете List<Product> products в Category, вы фактически начинаете использовать внутри entity обычную Java-коллекцию. И тут включаются старые добрые проблемы: null, внезапные NullPointerException, случайная замена списка, и «почему у меня всё работает в одном тесте, а потом падает в другом».

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

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;

@Entity // Категория как сущность-родитель
public class Category {

    @OneToMany(mappedBy = "category") // Обратная сторона связи (смотрим на Product.category)
    private List<Product> products = new ArrayList<>(); // Пустой список вместо null
}

Это избавляет от кучи «защитного кода» уровня:

if (category.getProducts() != null) { ... }

Вторая тонкость — тип поля. В поле обычно пишут интерфейс List, а не конкретную реализацию ArrayList. И это не снобизм, а практичная вещь: Hibernate может подменять коллекцию на свою внутреннюю реализацию (например, для lazy-механики и отслеживания изменений). Если вы зафиксируете конкретный класс, вы ограничите ORM (и себя).

Третья тонкость — не делайте коллекцию final в entity. В обычной Java-модели final — это хорошо: меньше неожиданностей. Но в ORM-мире это может стать проблемой, потому что провайдер может захотеть заменить коллекцию на «умную» коллекцию. final этому мешает. Для value-объектов мы можем обсуждать неизменяемость, но коллекции связей — это не та зона, где стоит начинать с жёстких ограничений.

И наконец, важный момент про «замену всей коллекции». Иногда пишут сеттер:

public void setProducts(List<Product> products) {
    this.products = products;
}

Формально это работает, но методически (и часто практично) это опасно. Заменяя весь список, вы легко ломаете внутренние ожидания ORM и теряете контроль над тем, какие элементы удалились, какие добавились, и что это означает для связи. Гораздо здоровее держать коллекцию как “живой контейнер” и управлять её содержимым аккуратно. Пока достаточно запомнить: коллекция — это часть связи, а не случайное поле со списком, поэтому её не стоит бездумно заменять целиком.

7. Мини-карта проекта: связи и поля

Чтобы закрепить идею, полезно прямо сейчас иметь в голове не абстрактные “Parent/Child”, а конкретные связи нашего mini-shop. У нас по сути две «учебные витрины», на которых мы будем тренировать мозг:

1. Category ↔ Product
2. CustomerOrder ↔ OrderItem

Они похожи по форме (один ко многим), но у них разный смысл в предметной области. Сегодня мы пока не обсуждаем каскады и жизненный цикл, но уже сейчас важно увидеть: механика mappedBy одинаковая.

Небольшая таблица, которая помогает не путаться:

Если хотите ещё более «картинно», можно держать в голове и такую схему:

flowchart TD
    Category["Category (parent)"]
    Product["Product (child)"]
    CustomerOrder["CustomerOrder (parent)"]
    OrderItem["OrderItem (child)"]

    Product -- "FK: category_id" --> Category
    OrderItem -- "FK: customer_order_id" --> CustomerOrder

    Category -. "products (mappedBy: category)" .-> Product
    CustomerOrder -. "items (mappedBy: customerOrder)" .-> OrderItem

Пунктиром я специально показываю «обратную навигацию». Она существует в объектной модели, но физически опирается на FK в ребёнке.

И это как раз то, что очень легко забыть, если смотреть только на Java-код: коллекция в родителе выглядит как «у меня тут список детей», но за этим списком стоит то, что дети хранят FK. То есть коллекция — это, по сути, удобный фасад над запросом «дай мне всех детей, которые ссылаются на меня».

8. Типичные ошибки при работе с @OneToMany

Ошибки с @OneToMany и mappedBy часто возникают не потому, что студент “невнимательный”, а потому что мозг пытается совместить две модели мира сразу: объектную (с ссылками и коллекциями) и реляционную (с внешними ключами и JOIN). Это нормально. Но есть несколько граблей, на которые лучше наступить в учебной аудитории, чем в коммерческом проекте на проде.

Ошибка №1: писать в mappedBy имя колонки, а не имя поля.
Это самый популярный промах. Вы видите в базе category_id и логично хотите написать mappedBy = "category_id". Но JPA ищет поле в Java-классе ребёнка, а не колонку. Правильно — mappedBy = "category", потому что поле в Product называется category. Если помнить правило “mappedBy — имя поля на стороне @ManyToOne”, вы почти всегда спасены.

Ошибка №2: забыть mappedBy и случайно получить join table.
Когда mappedBy отсутствует, ORM считает, что @OneToMany — самостоятельная связь, которую надо где-то хранить. Очень часто результатом становится лишняя таблица-связка. Вроде бы всё «завелось», приложение стартует, но схема распухает и начинает жить своей жизнью. В учебном проекте это особенно коварно: вы можете долго не замечать проблему, а потом удивляться, почему в базе появилась странная таблица.

Ошибка №3: оставлять коллекцию null и ловить NullPointerException в самый неловкий момент.
Если products или items не инициализированы, любой вызов category.getProducts().add(...) превращается в «бах» на ровном месте. И эта ошибка всегда случается тогда, когда вы уже устали и уверены, что “ну тут точно всё просто”. Инициализация new ArrayList<>() прямо в поле — маленькая привычка, которая экономит много времени.

Ошибка №4: думать, что @OneToMany создаёт второй FK или “записывает связь” сам по себе.
Интуитивно хочется верить, что если у Category есть products, то добавление товара в этот список автоматически запишет правильный FK. Но в реальности всё чуть сложнее: связь хранится на стороне ребёнка, и именно там живёт «настоящая» ссылка. Коллекция нужна для навигации, но FK по-прежнему живёт у ребёнка. Поэтому ожидание “достаточно просто добавить в список, а остальное JPA угадает” почти всегда заканчивается неприятным сюрпризом.

Ошибка №5: пытаться «упростить» модель и хранить вместо связи только categoryId в Product.
Иногда кажется, что объектная ссылка — лишняя роскошь, и проще держать Long categoryId. Но тогда вы теряете саму идею ORM-модели: вы перестаёте выражать связь как часть домена, и превращаете entity в полу-SQL DTO. В нашем курсе мы сознательно учимся моделировать связи как ссылки на сущности, а не как набор «id-шников», потому что это база для дальнейшего понимания JPA-поведения.