Spring Data JPA – repozytoria, zapytania, paginacja

Spring Data JPA to jeden z najczęściej wykorzystywanych modułów ekosystemu Spring, który znacząco upraszcza komunikację z relacyjnymi bazami danych. Dzięki mechanizmowi repozytoriów pozwala ograniczyć ilość kodu odpowiedzialnego za dostęp do danych, automatycznie generować zapytania oraz korzystać z gotowych rozwiązań do paginacji, sortowania czy audytowania encji.

W tym artykule omówię architekturę Spring Data JPA, dostępne interfejsy repozytoriów oraz sposoby wykonywania zapytań – od prostych metod Query Methods po bardziej zaawansowane mechanizmy @Query. Pokażę również, jak wykorzystywać projekcje, zarządzać paginacją oraz unikać najczęstszych problemów związanych z wydajnością i dostępem do danych.

Spis treści

Czym jest Spring Data?

Spring Data to projekt należący do ekosystemu Spring Framework, którego głównym celem jest uproszczenie dostępu do danych w aplikacjach Java. Dostarcza zestaw abstrakcji i narzędzi pozwalających na komunikację z różnymi systemami przechowywania danych, zarówno relacyjnymi bazami danych, jak i rozwiązaniami NoSQL.

Jednym z najważniejszych elementów Spring Data jest mechanizm repozytoriów (Repository), który ogranicza ilość kodu potrzebnego do wykonywania podstawowych operacji na danych, takich jak zapisywanie, odczytywanie, aktualizowanie czy usuwanie rekordów.

Architektura Spring Data JPA

Spring Data JPA wykorzystuje wzorzec Repository, którego zadaniem jest oddzielenie logiki biznesowej aplikacji od mechanizmów dostępu do danych. Dzięki temu warstwa serwisowa nie musi bezpośrednio korzystać z EntityManager czy SessionFactory ani implementować podstawowych operacji na bazie danych.

W tradycyjnym podejściu do komunikacji z bazą danych programista musi samodzielnie implementować warstwę dostępu do danych (DAO – Data Access Object). Nawet w przypadku wykorzystania Hibernate konieczne jest napisanie kodu odpowiedzialnego za wykonywanie poszczególnych operacji.

Spring Data pozwala znacząco ograniczyć tę pracę poprzez:

  • Automatyczne generowanie implementacji repozytoriów – programista definiuje interfejs, a Spring Data tworzy jego implementację.
  • Obsługę podstawowych operacji CRUD – gotowe metody umożliwiają zapisywanie, pobieranie i usuwanie danych.
  • Generowanie zapytań na podstawie nazw metod – przykładowo metoda findByEmail(String email) pozwala wyszukać użytkownika na podstawie jego adresu e-mail bez konieczności ręcznego pisania zapytania.
  • Obsługę paginacji i sortowania – gotowe mechanizmy pozwalają pobierać dane partiami i określać kolejność wyników.
  • Integrację z mechanizmami Spring Framework – między innymi z zarządzaniem transakcjami.

Spring Data a Spring Data JPA

Warto zaznaczyć, że Spring Data nie jest pojedynczą biblioteką przeznaczoną wyłącznie do obsługi relacyjnych baz danych. Jest to zbiór projektów, z których każdy odpowiada za integrację z określoną technologią przechowywania danych.

Do najważniejszych modułów należą:

ModułZastosowanie
Spring Data JPAObsługa relacyjnych baz danych za pomocą JPA
Spring Data JDBCDostęp do relacyjnych baz danych bez wykorzystania JPA
Spring Data MongoDBIntegracja z dokumentową bazą MongoDB
Spring Data RedisIntegracja z magazynem danych Redis
Spring Data R2DBCReaktywny dostęp do relacyjnych baz danych
Spring Data ElasticsearchIntegracja z wyszukiwarką Elasticsearch

W tej notce skupię się na module Spring Data JPA.

Wzorzec Repository

Repository to wzorzec projektowy, który udostępnia interfejs umożliwiający wykonywanie operacji na obiektach domenowych. Stanowi warstwę pośrednią między logiką biznesową a mechanizmem persystencji.

W Spring Data JPA repozytorium jest najczęściej definiowane jako interfejs rozszerzający JpaRepository.

Automatyczne tworzenie implementacji repozytoriów

Jedną z najważniejszych cech Spring Data JPA jest możliwość automatycznego tworzenia implementacji repozytoriów na podstawie zdefiniowanych interfejsów.

Podczas uruchamiania aplikacji Spring Data JPA:

  1. Wyszukuje interfejsy repozytoriów w odpowiednich pakietach.
  2. Analizuje ich deklaracje, między innymi typ encji oraz identyfikatora.
  3. Tworzy obiekty proxy implementujące interfejsy repozytoriów.
  4. Rejestruje utworzone obiekty jako beany w kontenerze Spring.

Współpraca Spring Data JPA z Hibernate

Spring Data JPA nie komunikuje się bezpośrednio z relacyjną bazą danych. Wykorzystuje do tego interfejs EntityManager, będący częścią specyfikacji JPA.

W typowej aplikacji Spring Boot dostawcą implementacji JPA jest Hibernate.

Przepływ wywołania można przedstawić następująco:

UserService
    |
    v
UserRepository (Spring Data Proxy)
    |
    v
Spring Data JPA
    |
    v
EntityManager (JPA)
    |
    v
Hibernate
    |
    v
JDBC
    |
    v
Relacyjna baza danych

Tworzenie pierwszego repozytorium

Aby stworzyć swoje własne repozytorium, wystarczy napisać interfejs, który będzie rozszerzał JpaRepository.

Przykładowo, dla encji User można utworzyć następujące repozytorium:

public interface UserRepository
        extends JpaRepository<User, Long> {

    Optional<User> findByEmail(String email);
}

Interfejs JpaRepository przyjmuje dwa parametry generyczne:

  • User – typ encji obsługiwanej przez repozytorium.
  • Long – typ klucza głównego encji.

Repozytorium można następnie wstrzyknąć do warstwy serwisowej za pomocą mechanizmu Dependency Injection.

@Service
public class UserService {

    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public Optional<User> findByEmail(String email) {
        return userRepository.findByEmail(email);
    }
}

Konfiguracja repozytoriów

W aplikacjach Spring Boot korzystających z spring-boot-starter-data-jpa konfiguracja repozytoriów odbywa się zazwyczaj automatycznie.

Spring Boot wyszukuje interfejsy repozytoriów w pakiecie klasy oznaczonej @SpringBootApplication oraz jego podpakietach.

Nie ma potrzeby oznaczania każdego interfejsu repozytorium adnotacją @Repository, ponieważ Spring Data JPA samodzielnie rejestruje odpowiednie beany.

Jeżeli repozytoria znajdują się poza standardowym zakresem skanowania, można jawnie określić ich lokalizację za pomocą adnotacji @EnableJpaRepositories.

@Configuration
@EnableJpaRepositories(
    basePackages = "com.example.repository"
)
public class JpaConfig {
}

Takie rozwiązanie bywa przydatne w aplikacjach posiadających bardziej rozbudowaną strukturę pakietów lub korzystających z wielu źródeł danych.

Tworzenie repozytoriów w Spring Data JPA

Spring Data udostępnia kilka interfejsów repozytoriów, które różnią się zakresem oferowanych funkcjonalności. Dzięki temu programista może zdecydować, czy potrzebuje jedynie podstawowych operacji CRUD, mechanizmów paginacji i sortowania, czy również funkcjonalności specyficznych dla JPA.

Repository

Repository<T, ID> to podstawowy interfejs w hierarchii Spring Data. Nie deklaruje żadnych metod, ale umożliwia Spring Data rozpoznawanie i tworzenie repozytoriów dla określonych typów encji.

public interface UserRepository
        extends Repository<User, Long> {

    Optional<User> findById(Long id);

    User save(User user);
}

Takie podejście pozwala ograniczyć dostępne operacje wyłącznie do metod zadeklarowanych w interfejsie.

CrudRepository

CrudRepository<T, ID> rozszerza Repository i udostępnia zestaw metod służących do wykonywania podstawowych operacji CRUD (Create, Read, Update, Delete).

public interface UserRepository
        extends CrudRepository<User, Long> {
}

Najważniejsze metody tego interfejsu to:

MetodaZastosowanie
save(entity)Zapisuje nową lub istniejącą encję
saveAll(entities)Zapisuje kolekcję encji
findById(id)Pobiera encję na podstawie identyfikatora
findAll()Pobiera wszystkie encje
findAllById(ids)Pobiera encje o podanych identyfikatorach
existsById(id)Sprawdza istnienie encji
count()Zwraca liczbę encji
deleteById(id)Usuwa encję na podstawie identyfikatora
delete(entity)Usuwa wskazaną encję
deleteAll()Usuwa wszystkie encje

Warto zwrócić uwagę, że metody findAll() oraz findAllById() zwracają Iterable<T>, a nie List<T>.

ListCrudRepository

Interfejs ListCrudRepository<T, ID> został wprowadzony w Spring Data 3.0 jako wygodniejsza alternatywa dla CrudRepository.

Udostępnia analogiczne operacje, ale metody zwracające wiele encji wykorzystują List<T> zamiast Iterable<T>.

public interface UserRepository
        extends ListCrudRepository<User, Long> {
}

Przykładowo:

List<User> users = userRepository.findAll();

Takie rozwiązanie eliminuje konieczność samodzielnej konwersji Iterable na List.

PagingAndSortingRepository

PagingAndSortingRepository<T, ID> udostępnia metody umożliwiające pobieranie danych z uwzględnieniem sortowania i paginacji.

Najważniejsze z nich to:

Iterable<T> findAll(Sort sort);

Page<T> findAll(Pageable pageable);

Od Spring Data 3.0 PagingAndSortingRepository nie rozszerza już CrudRepository. Oznacza to, że jeśli potrzebne są zarówno operacje CRUD, jak i paginacja, należy rozszerzyć oba interfejsy.

public interface UserRepository
        extends CrudRepository<User, Long>,
                PagingAndSortingRepository<User, Long> {
}

Spring Data udostępnia również ListPagingAndSortingRepository, który dla sortowanych wyników zwraca List<T> zamiast Iterable<T>.

Mechanizmy paginacji i sortowania zostaną dokładniej omówione w osobnym rozdziale.

JpaRepository

JpaRepository<T, ID> to najczęściej wykorzystywany interfejs w aplikacjach Spring Data JPA.

Rozszerza między innymi ListCrudRepository, ListPagingAndSortingRepository oraz QueryByExampleExecutor, dzięki czemu udostępnia zarówno podstawowe operacje CRUD, jak i dodatkowe mechanizmy związane z JPA.

public interface UserRepository
        extends JpaRepository<User, Long> {
}

Oprócz wcześniej opisanych metod udostępnia między innymi:

MetodaZastosowanie
flush()Synchronizuje zmiany z bazą danych
saveAndFlush(entity)Zapisuje encję i wykonuje flush
saveAllAndFlush(entities)Zapisuje kolekcję encji i wykonuje flush
getReferenceById(id)Pobiera referencję do encji
deleteAllInBatch()Usuwa wszystkie encje pojedynczym zapytaniem
deleteAllByIdInBatch(ids)Usuwa encje o wskazanych identyfikatorach jednym zapytaniem

Warto pamiętać, że flush() nie oznacza zatwierdzenia transakcji (commit). Powoduje jedynie synchronizację zmian znajdujących się w kontekście persystencji z bazą danych.

Z kolei metody usuwania zbiorczego deleteAllInBatch() omijają standardowe mechanizmy usuwania poszczególnych encji, w tym zdarzenia cyklu życia JPA oraz kaskadowe usuwanie realizowane przez JPA. Mogą również spowodować niespójność pomiędzy kontekstem persystencji a stanem bazy danych.

Automatyczne generowanie zapytań (Query Methods)

Spring Data JPA umożliwia tworzenie zapytań do bazy danych bez konieczności ręcznego pisania SQL lub JPQL. Wystarczy zadeklarować metodę w interfejsie repozytorium, a framework na podstawie jej nazwy automatycznie przygotuje odpowiednie zapytanie.

Mechanizm ten nazywany jest Query Methods lub Derived Query Methods.

Przykładowo, aby wyszukać użytkownika na podstawie adresu e-mail, wystarczy zadeklarować następującą metodę:

public interface UserRepository
        extends JpaRepository<User, Long> {

    Optional<User> findByEmail(String email);
}

Spring Data JPA interpretuje nazwę findByEmail() i tworzy zapytanie odpowiadające następującemu JPQL:

SELECT u FROM User u WHERE u.email = ?1

Hibernate przekształca następnie zapytanie JPQL w odpowiedni SQL wykonywany na bazie danych.

Jak Spring Data interpretuje nazwy metod?

Nazwa metody składa się z dwóch podstawowych części:

  • Subject – określa rodzaj operacji, np. find, count, exists lub delete.
  • Predicate – określa warunki wyszukiwania, czyli część nazwy występującą po słowie By.

Przykładowo:

List<User> findByNameAndEmail(
        String name, String email);

Spring Data JPA interpretuje metodę w następujący sposób:

  • find – pobierz dane.
  • By – początek warunków zapytania.
  • Name – pole name w encji User.
  • And – operator logiczny AND.
  • Email – pole email w encji User.

W rezultacie powstaje zapytanie odpowiadające:

SELECT u FROM User u
WHERE u.name = ?1 AND u.email = ?2

Warto zauważyć, że Spring Data JPA odwołuje się do nazw właściwości encji Java, a nie nazw kolumn w bazie danych.

Jeżeli pole email zostanie usunięte lub jego nazwa ulegnie zmianie, a metoda repozytorium nie zostanie odpowiednio zaktualizowana, Spring Data JPA zazwyczaj zgłosi błąd podczas inicjalizacji repozytorium.

Podstawowe rodzaje zapytań

Spring Data JPA udostępnia kilka podstawowych prefiksów pozwalających określić rodzaj wykonywanej operacji.

PrefiksPrzykładZastosowanie
findByfindByEmailWyszukiwanie danych
findAllByfindAllByNameWyszukiwanie kolekcji danych
existsByexistsByEmailSprawdzanie istnienia danych
countBycountByNameZliczanie rekordów
deleteBydeleteByEmailUsuwanie danych

Przykładowa implementacja repozytorium może wyglądać następująco:

public interface UserRepository
        extends JpaRepository<User, Long> {

    Optional<User> findByEmail(String email);

    List<User> findAllByName(String name);

    boolean existsByEmail(String email);

    long countByName(String name);

    long deleteByEmail(String email);
}

W przypadku findByEmail() zastosowanie Optional<User> oznacza, że metoda powinna zwrócić maksymalnie jeden rekord. Jeżeli zapytanie znajdzie więcej niż jedną encję, zostanie zgłoszony wyjątek.

Warto również pamiętać, że deleteBy nie oznacza automatycznie wykonania jednego zapytania SQL DELETE. W przypadku zapytań pochodnych Spring Data JPA najpierw pobiera pasujące encje, a następnie usuwa je pojedynczo. Ma to znaczenie między innymi dla wydajności i obsługi zdarzeń cyklu życia JPA.

Metody usuwające wymagają również odpowiednio skonfigurowanej transakcji.

Operatory wykorzystywane w nazwach metod

Spring Data JPA obsługuje szereg operatorów, które pozwalają konstruować bardziej rozbudowane warunki wyszukiwania.

W poniższych przykładach zakładam, że encja User posiada dodatkowo pola age oraz active.

OperatorPrzykład
AndfindByNameAndEmail
OrfindByNameOrEmail
GreaterThanfindByAgeGreaterThan
LessThanfindByAgeLessThan
BetweenfindByAgeBetween
InfindByAgeIn
NotfindByNameNot
IsNullfindByEmailIsNull
IsNotNullfindByEmailIsNotNull
TruefindByActiveTrue
FalsefindByActiveFalse
LikefindByNameLike
ContainingfindByNameContaining
StartingWithfindByNameStartingWith
EndingWithfindByNameEndingWith

Przykładowo:

List<User> findByAgeBetween(
        int minAge, int maxAge);

Odpowiada zapytaniu:

SELECT u FROM User u
WHERE u.age BETWEEN ?1 AND ?2

Z kolei metoda:

List<User> findByAgeIn(Collection<Integer> ages);

Pozwala wyszukać użytkowników, których wiek znajduje się w przekazanej kolekcji.

Wyszukiwanie fragmentów tekstu

W przypadku operacji na polach tekstowych szczególnie przydatne są operatory Containing, StartingWith oraz EndingWith.

Przykładowo:

List<User> findByNameContaining(String name);

Dla argumentu "John" Spring Data JPA utworzy warunek odpowiadający:

WHERE u.name LIKE '%John%'

W przeciwieństwie do operatora Like, nie trzeba samodzielnie dodawać znaków % do przekazywanego parametru.

Dostępny jest również modyfikator IgnoreCase, który pozwala wykonywać porównania bez uwzględniania wielkości liter.

List<User> findByNameContainingIgnoreCase(
        String name);

Dzięki temu zapytanie będzie mogło znaleźć zarówno "John", jak i "john" czy "JOHN".

Sortowanie wyników

Spring Data JPA umożliwia określenie kolejności zwracanych rekordów bezpośrednio w nazwie metody.

List<User> findByActiveTrueOrderByAgeAsc();

Powyższa metoda pobierze aktywnych użytkowników, sortując ich rosnąco według wieku.

Dostępne są dwa podstawowe kierunki sortowania:

  • Asc – sortowanie rosnące.
  • Desc – sortowanie malejące.

Możliwe jest również sortowanie według kilku właściwości:

List<User> findByActiveTrueOrderByNameAscAgeDesc();

W tym przypadku użytkownicy zostaną posortowani najpierw alfabetycznie według imienia, a następnie malejąco według wieku.

Jeżeli kierunek sortowania powinien być ustalany dynamicznie, można wykorzystać parametr Sort.

List<User> findByActiveTrue(Sort sort);

Przykładowe wywołanie:

userRepository.findByActiveTrue(
        Sort.by(Sort.Direction.DESC, "age"));

Mechanizm Sort zostanie omówiony dokładniej w rozdziale dotyczącym paginacji.

Ograniczanie liczby wyników – First i Top

Spring Data JPA pozwala również ograniczyć liczbę zwracanych rekordów za pomocą słów kluczowych First i Top.

Przykładowo, aby pobrać trzech najstarszych użytkowników:

List<User> findTop3ByOrderByAgeDesc();

Aby pobrać jednego najmłodszego użytkownika:

Optional<User> findFirstByOrderByAgeAsc();

Oba słowa kluczowe działają analogicznie. Jeżeli nie zostanie podana liczba, domyślnie zwracany jest maksymalnie jeden rekord.

Warto zwrócić uwagę, że ograniczanie wyników za pomocą Top lub First bez określenia kolejności sortowania może prowadzić do nieprzewidywalnych rezultatów, ponieważ baza danych nie gwarantuje domyślnej kolejności rekordów.

Ograniczenia mechanizmu Query Methods

Chociaż automatyczne generowanie zapytań jest bardzo wygodne, nie sprawdza się w każdej sytuacji.

Przykładowo, metoda:

List<User> findByNameContainingIgnoreCaseAndAgeGreaterThanAndActiveTrueOrderByAgeDesc(
        String name, int age);

jest poprawna, ale jej nazwa staje się długa i trudna do odczytania.

Problem pojawia się również w przypadku bardziej złożonych zapytań, szczególnie gdy wymagane są:

  • Zaawansowane warunki logiczne z grupowaniem AND i OR.
  • Agregacje i grupowanie wyników.
  • Złożone połączenia pomiędzy encjami.
  • Dynamiczne warunki zależne od parametrów przekazanych przez użytkownika.

W takich sytuacjach lepszym rozwiązaniem może być wykorzystanie adnotacji @Query lub mechanizmu Specification (w tej notce nie zamierzam go jednak opisywać, zachęcam do zerknięcia do specyfikacji Springa).

Query Methods najlepiej sprawdzają się przy prostych zapytaniach, których przeznaczenie można łatwo odczytać z nazwy metody. W przypadku bardziej skomplikowanej logiki wyszukiwania warto skorzystać z mechanizmów oferujących większą kontrolę nad konstrukcją zapytania.

Tworzenie własnych zapytań za pomocą @Query

Spring Data JPA udostępnia adnotację @Query, która umożliwia samodzielne definiowanie zapytań bezpośrednio w interfejsie repozytorium.

Zapytania można zapisywać za pomocą dwóch języków:

  • JPQL (Jakarta Persistence Query Language) – język operujący na encjach i ich właściwościach.
  • Native SQL – standardowy SQL wykonywany bezpośrednio przez bazę danych.

Zapytania JPQL

JPQL to język zapytań stanowiący część specyfikacji JPA. Jego składnia przypomina SQL, jednak zamiast odwoływać się do tabel i kolumn, operuje na encjach Java oraz ich właściwościach.

Przykładowo, aby pobrać wszystkich aktywnych użytkowników, można zdefiniować następującą metodę:

public interface UserRepository
        extends JpaRepository<User, Long> {

    @Query("SELECT u FROM User u WHERE u.active = true")
    List<User> findActiveUsers();
}

W powyższym przykładzie:

  • User oznacza nazwę encji JPA, a nie tabeli w bazie danych.
  • u to alias encji.
  • u.active odnosi się do właściwości active klasy User.

Hibernate przekształci zapytanie JPQL w odpowiedni SQL, uwzględniając mapowania encji oraz dialekt wykorzystywanej bazy danych.

JPQL pozwala również tworzyć bardziej rozbudowane zapytania, np. z wykorzystaniem agregacji:

@Query("""
    SELECT COUNT(u)
    FROM User u
    WHERE u.active = true
    """)
long countActiveUsers();

Warto pamiętać, że zapytania JPQL nie są wykonywane bezpośrednio przez bazę danych. Najpierw są interpretowane przez dostawcę JPA, np. Hibernate, który generuje odpowiedni SQL.

Zapytania Native SQL

Spring Data JPA pozwala również wykonywać natywne zapytania SQL, z pominięciem etapu tłumaczenia JPQL na SQL.

W tym celu należy ustawić parametr nativeQuery = true.

@Query(
    value = "SELECT * FROM users WHERE active = true",
    nativeQuery = true
)
List<User> findActiveUsersNative();

W przeciwieństwie do JPQL, w przypadku natywnego SQL należy korzystać z rzeczywistych nazw tabel i kolumn znajdujących się w bazie danych.

Takie rozwiązanie jest szczególnie przydatne, gdy zapytanie:

  • Wykorzystuje funkcje charakterystyczne dla konkretnej bazy danych.
  • Zawiera zaawansowane konstrukcje SQL, których nie obsługuje JPQL.

Przekazywanie parametrów – @Param

W większości przypadków zapytania wymagają przekazania parametrów, np. adresu e-mail, wieku użytkownika czy identyfikatora encji.

Spring Data JPA obsługuje dwa podstawowe sposoby wiązania parametrów.

Parametry pozycyjne

W pierwszym podejściu parametry identyfikowane są na podstawie ich pozycji w deklaracji metody.

@Query("""
    SELECT u FROM User u
    WHERE u.name = ?1 AND u.age >= ?2
    """)
List<User> findUsers(String name, int minAge);

Oznaczenia ?1 i ?2 odpowiadają kolejnym argumentom metody.

Parametry nazwane

Drugie podejście polega na wykorzystaniu adnotacji @Param, która pozwala jawnie powiązać argument metody z parametrem zapytania.

@Query("""
    SELECT u FROM User u
    WHERE u.name = :name AND u.age >= :minAge
    """)
List<User> findUsers(
    @Param("name") String name,
    @Param("minAge") int minAge
);

Parametry nazwane są zazwyczaj czytelniejsze, szczególnie w przypadku zapytań posiadających kilka warunków.

Aktualizowanie danych – @Modifying

Adnotacja @Query może być wykorzystywana nie tylko do pobierania danych, ale również do wykonywania operacji UPDATE i DELETE.

W takich przypadkach należy dodatkowo zastosować adnotację @Modifying, która informuje Spring Data JPA, że zapytanie modyfikuje dane.

Przykładowo, aby dezaktywować wszystkich użytkowników poniżej określonego wieku:

@Modifying
@Query("""
    UPDATE User u
    SET u.active = false
    WHERE u.age < :age
    """)
int deactivateUsers(@Param("age") int age);

Metoda zwraca liczbę rekordów objętych operacją.Istotne jest również to, że zapytania modyfikujące wymagają aktywnej transakcji.

Paginacja i sortowanie

Podczas pracy z relacyjnymi bazami danych często pojawia się potrzeba pobierania dużej liczby rekordów. Spring Data JPA udostępnia mechanizmy paginacji (pagination) i sortowania (sorting), które pozwalają kontrolować liczbę pobieranych rekordów oraz kolejność zwracanych wyników.

Pageable i PageRequest

Podstawą mechanizmu paginacji w Spring Data jest interfejs Pageable, który przechowuje informacje o numerze strony, jej rozmiarze oraz sposobie sortowania wyników.

Najczęściej wykorzystywaną implementacją tego interfejsu jest PageRequest.

Przykładowo, aby pobrać pierwszych 10 użytkowników, wystarczy wykonać:

Pageable pageable = PageRequest.of(0, 10);

Page<User> users = userRepository.findAll(pageable);

Metoda PageRequest.of() przyjmuje dwa podstawowe argumenty:

  • page – numer strony, indeksowany od 0.
  • size – maksymalna liczba rekordów na stronie.

Oznacza to, że PageRequest.of(0, 10) pobierze pierwszych 10 użytkowników, natomiast PageRequest.of(1, 10) pobierze kolejnych 10.

Page – pobieranie stron z metadanymi

Interfejs Page<T> reprezentuje stronę wyników wraz z dodatkowymi informacjami dotyczącymi całego zbioru danych.

Przykładowo:

Pageable pageable = PageRequest.of(0, 10);

Page<User> page = userRepository.findAll(pageable);

List<User> users = page.getContent();

long totalElements = page.getTotalElements();
int totalPages = page.getTotalPages();

boolean hasNext = page.hasNext();
boolean hasPrevious = page.hasPrevious();

Slice – paginacja bez zliczania wszystkich rekordów

Nie zawsze potrzebna jest informacja o całkowitej liczbie rekordów i dostępnych stronach.

Przykładowo, w aplikacji wykorzystującej mechanizm infinite scroll wystarczy wiedzieć, czy istnieją kolejne rekordy do pobrania. Nie będę jednak go omawiał w tej notce.

Spring Data JPA umożliwia również wykorzystanie List<T> jako typu zwracanego przez metodę przyjmującą Pageable.

List<User> findByActiveTrue(Pageable pageable);

W takim przypadku Spring Data ogranicza liczbę pobieranych rekordów, ale nie przygotowuje dodatkowych metadanych dotyczących paginacji ani nie wykonuje zapytania zliczającego. Potraktuj to jak zwykłe zapytanie SQL typu SELECT z ograniczeniem za pomocą LIMIT.

Podsumowując::

  • Page – gdy potrzebne są numery stron i całkowita liczba wyników.
  • Slice – gdy wystarczy wiedzieć, czy istnieje kolejna partia danych.
  • List – gdy potrzebna jest jedynie ograniczona lista rekordów bez dodatkowych metadanych.

Sortowanie wyników – Sort

Spring Data JPA udostępnia klasę Sort, która umożliwia dynamiczne określanie kolejności wyników.

Przykładowo, aby pobrać użytkowników posortowanych rosnąco według imienia:

List<User> users = userRepository.findAll(
        Sort.by("name").ascending()
);

Sortowanie malejące:

Sort sort = Sort.by("age").descending();

Można również łączyć kilka warunków sortowania:

Sort sort = Sort.by("name").ascending()
        .and(Sort.by("age").descending());

W takim przypadku dane zostaną posortowane najpierw rosnąco według imienia, a następnie malejąco według wieku.

Łączenie paginacji i sortowania

Sortowanie można również przekazać bezpośrednio do PageRequest.

Pageable pageable = PageRequest.of(
        0,
        10,
        Sort.by("age").descending()
);

Page<User> page = userRepository.findAll(pageable);

Przy takim podejściu mam pewność, że kolejność zwracanych elementów zawsze będzie taka sama.

Podczas korzystania z paginacji i sortowania warto pamiętać o kilku zasadach:

  1. Stosuj stabilne sortowanie – najlepiej uwzględniające unikalny identyfikator encji. Samo sortowanie po wieku czy nazwisku może prowadzić do niejednoznacznej kolejności rekordów.
  2. Ograniczaj maksymalny rozmiar strony – nie pozwalaj klientowi API pobierać dowolnie dużej liczby rekordów.
  3. Nie stosuj Page, jeśli nie potrzebujesz całkowitej liczby wyników – Slice lub List mogą ograniczyć liczbę wykonywanych zapytań.
  4. Zadbaj o indeksy – szczególnie na kolumnach wykorzystywanych do filtrowania i sortowania.

Projekcje w Spring Data JPA

Podczas pobierania danych z bazy nie zawsze potrzebujemy wszystkich pól encji. Przykładowo, jeżeli aplikacja wyświetla listę użytkowników zawierającą jedynie identyfikator i imię, pobieranie pozostałych informacji może być niepotrzebne.

Spring Data JPA udostępnia mechanizm projekcji (Projections), który pozwala określić, jakie dane powinny zostać zwrócone przez repozytorium.

Zamiast pobierać wszystkie kolumny encji, można ograniczyć zapytanie do:

SELECT id, name
FROM users
WHERE active = true;

Spring Data JPA udostępnia dwa podstawowe sposoby definiowania projekcji: Interface-based Projections oraz DTO Projections.

Interface-based Projections

Pierwszym rozwiązaniem są projekcje oparte na interfejsach, które zawierają wyłącznie metody dostępowe do potrzebnych właściwości encji.

Przykładowo:

public interface UserSummaryView {
    Long getId();
    String getName();
}

Następnie wystarczy wykorzystać interfejs jako typ zwracany przez metodę repozytorium:

public interface UserRepository
        extends JpaRepository<User, Long> {

    List<UserSummaryView> findByActiveTrue();
}

Spring Data JPA automatycznie przygotuje odpowiednie zapytanie, pobierając jedynie wymagane właściwości.

Wynikiem nie będą pełne encje User, ale obiekty proxy implementujące interfejs UserSummaryView.

Closed i Open Projections

Spring Data rozróżnia dwa rodzaje projekcji interfejsowych:

  • Closed Projection – wszystkie metody odpowiadają właściwościom encji. Dzięki temu Spring Data może ograniczyć liczbę pobieranych kolumn.
  • Open Projection – umożliwia definiowanie wartości wyliczanych dynamicznie za pomocą wyrażeń SpEL.

Przykład Open Projection:

public interface UserSummaryView {

    String getName();

    @Value("#{target.name + ' (' + target.email + ')'}")
    String getDisplayName();
}

W tym przypadku metoda getDisplayName() zwróci imię użytkownika wraz z jego adresem e-mail.

Należy jednak pamiętać, że wykorzystanie SpEL ogranicza możliwości optymalizacji zapytania, ponieważ Spring Data nie zawsze może określić, które właściwości encji będą potrzebne.

DTO Projections

Drugim rozwiązaniem są projekcje oparte na klasach DTO (Data Transfer Object). W nowoczesnej Javie szczególnie wygodnym rozwiązaniem są rekordy (record).

Przykładowo:

public record UserSummary(
    Long id,
    String name
) {}

Następnie można wykorzystać taki rekord jako typ zwracany przez repozytorium:

public interface UserRepository
        extends JpaRepository<User, Long> {

    List<UserSummary> findByActiveTrue();
}

Spring Data JPA na podstawie konstruktora rekordu określi, które właściwości encji należy pobrać, i utworzy odpowiednie obiekty DTO.

W przeciwieństwie do projekcji interfejsowych nie są tutaj tworzone obiekty proxy.

DTO Projections z wykorzystaniem @Query

Projekcje DTO można również łączyć z wcześniej omówioną adnotacją @Query.

@Query("""
    SELECT new com.example.dto.UserSummary(
        u.id,
        u.name
    )
    FROM User u
    WHERE u.active = true
    """)
List<UserSummary> findActiveUserSummaries();

Konstrukcja SELECT new umożliwia bezpośrednie utworzenie obiektu DTO na podstawie wyników zapytania JPQL.

Należy pamiętać, że konstruktor DTO musi odpowiadać liczbie, kolejności oraz typom przekazywanych wartości.

Kiedy warto stosować projekcje?

Projekcje sprawdzają się przede wszystkim w operacjach odczytu, gdy aplikacja potrzebuje jedynie części informacji przechowywanych w encji.

Są szczególnie przydatne podczas:

  • Przygotowywania danych do odpowiedzi REST API.
  • Pobierania list zawierających tylko wybrane pola.
  • Generowania raportów i zestawień.
  • Optymalizowania zapytań do bazy danych.

Warto pamiętać, że projekcje nie zawsze gwarantują pobranie wyłącznie wskazanych kolumn. Szczególnie w przypadku zagnieżdżonych właściwości i relacji między encjami mogą pojawić się dodatkowe złączenia JOIN.

W praktyce projekcje DTO oparte na rekordach są dobrym rozwiązaniem do przygotowywania odpowiedzi REST API, natomiast projekcje interfejsowe umożliwiają szybkie definiowanie prostych widoków danych bez konieczności tworzenia dodatkowych klas.

Audytowanie encji w Spring Data JPA

Spring Data JPA udostępnia mechanizm audytowania encji (Auditing), który umożliwia automatyczne zapisywanie informacji o tym, kiedy dany rekord został utworzony lub zmodyfikowany oraz kto wykonał daną operację.

Do tego celu wykorzystywane są cztery podstawowe adnotacje:

AdnotacjaZastosowanie
@CreatedDateData utworzenia rekordu
@LastModifiedDateData ostatniej modyfikacji
@CreatedByUżytkownik, który utworzył rekord
@LastModifiedByUżytkownik, który ostatnio zmodyfikował rekord

Dzięki temu nie ma potrzeby ręcznego ustawiania tych wartości w metodach serwisowych.

Automatyczne zapisywanie dat

Aby skorzystać z mechanizmu audytowania, należy najpierw włączyć go za pomocą adnotacji @EnableJpaAuditing.

@Configuration
@EnableJpaAuditing
public class JpaConfig {
}

Następnie można oznaczyć odpowiednie pola encji:

@Entity
@EntityListeners(AuditingEntityListener.class)
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @CreatedDate
    private Instant createdAt;

    @LastModifiedDate
    private Instant updatedAt;

    // Gettery i settery
}

Adnotacja @EntityListeners rejestruje AuditingEntityListener, który reaguje na zdarzenia cyklu życia encji JPA.

Podczas zapisywania nowej encji Spring Data JPA automatycznie uzupełni pole createdAt, a przy późniejszych aktualizacjach będzie aktualizować updatedAt.

Domyślnie updatedAt może zostać ustawione również podczas tworzenia encji.

Automatyczne zapisywanie użytkownika – AuditorAware

Spring Data JPA pozwala również zapisywać informacje o użytkowniku, który utworzył lub zmodyfikował rekord.

Wystarczy dodać do encji odpowiednie pola:

@CreatedBy
private String createdBy;

@LastModifiedBy
private String lastModifiedBy;

W odróżnieniu od dat, Spring Data JPA nie jest w stanie samodzielnie określić, kto wykonuje operację. Konieczne jest dostarczenie implementacji interfejsu AuditorAware<T>.

Przykładowo, w aplikacji wykorzystującej Spring Security:

@Component
public class SecurityAuditorAware
        implements AuditorAware<String> {

    @Override
    public Optional<String> getCurrentAuditor() {

        Authentication auth =
            SecurityContextHolder.getContext()
                .getAuthentication();

        if (auth == null || !auth.isAuthenticated()
                || auth instanceof AnonymousAuthenticationToken) {
            return Optional.empty();
        }

        return Optional.of(auth.getName());
    }
}

W powyższym przykładzie Spring Data JPA wykorzystuje nazwę aktualnie uwierzytelnionego użytkownika do automatycznego uzupełniania pól createdBy i lastModifiedBy.

Kiedy warto stosować auditing?

Mechanizm audytowania jest szczególnie przydatny w aplikacjach, w których istotne jest śledzenie dat utworzenia i modyfikacji danych oraz identyfikowanie użytkowników odpowiedzialnych za zmiany.

Najczęstsze problemy i dobre praktyki w Spring Data JPA

Spring Data JPA znacząco upraszcza dostęp do danych, jednak automatyzacja wielu operacji może sprawić, że programista traci kontrolę nad wykonywanymi zapytaniami SQL. Dlatego warto znać najczęstsze problemy oraz zasady pozwalające uniknąć błędów wydajnościowych.

Problem N+1 i @EntityGraph

Jednym z najczęstszych problemów podczas korzystania z JPA jest problem N+1, który polega na wykonywaniu dodatkowych zapytań podczas pobierania powiązanych encji.

Problem ten szczegółowo omówiłem już w artykule dotyczącym Hibernate. W Spring Data JPA jednym ze sposobów jego rozwiązania jest wykorzystanie adnotacji @EntityGraph.

Załóżmy, że encja User posiada kolekcję zamówień:

@OneToMany(mappedBy = "user", fetch = FetchType.LAZY)
private List<Order> orders;

Aby pobrać użytkowników wraz z ich zamówieniami, można wykorzystać następującą metodę repozytorium:

@EntityGraph(attributePaths = {"orders"})
List<User> findByActiveTrue();

Adnotacja @EntityGraph informuje dostawcę JPA, że podczas pobierania użytkowników powinien również załadować powiązaną kolekcję orders.

W przypadku Hibernate może to skutkować wykonaniem jednego zapytania z JOIN, zamiast osobnych zapytań dla każdego użytkownika.

Warto jednak pamiętać, że pobieranie kolekcji za pomocą JOIN może prowadzić do zwracania wielu wierszy dla tej samej encji. Szczególnie problematyczne jest łączenie takiego rozwiązania z paginacją, ponieważ Hibernate może być zmuszony do wykonania paginacji w pamięci aplikacji.

Dlatego @EntityGraph należy stosować świadomie, analizując generowane zapytania SQL.

Transakcje w warstwie serwisowej

Spring Data JPA posiada domyślną obsługę transakcji dla standardowych metod repozytoriów. Nie oznacza to jednak, że każda operacja biznesowa powinna być wykonywana w osobnej transakcji.

Załóżmy, że metoda serwisowa musi zmodyfikować użytkownika oraz zapisać informację audytową.

@Transactional
public void updateUser(Long id, String name) {

    User user = userRepository.findById(id)
            .orElseThrow();

    user.setName(name);

    auditRepository.save(
        new AuditLog("Updated user: " + id)
    );
}

Dzięki zastosowaniu @Transactional na poziomie serwisu obie operacje uczestniczą w jednej transakcji.

Jeżeli wystąpi nieobsłużony wyjątek powodujący rollback, zmiany nie zostaną zatwierdzone.

Granice transakcji powinny zazwyczaj odpowiadać operacjom biznesowym, a nie pojedynczym wywołaniom repozytorium.

Niepotrzebne wywoływanie save()

Częstym błędem jest wywoływanie metody save() po każdej modyfikacji encji.

Przykładowo:

@Transactional
public void updateUser(Long id, String name) {

    User user = userRepository.findById(id)
            .orElseThrow();

    user.setName(name);

    userRepository.save(user);
}

W tym przypadku ostatnia instrukcja jest zbędna.

Ponieważ encja została pobrana w ramach aktywnej transakcji i pozostaje zarządzana przez Hibernate, mechanizm dirty checking automatycznie wykryje zmiany i zsynchronizuje je z bazą danych.

Wystarczy więc:

@Transactional
public void updateUser(Long id, String name) {

    User user = userRepository.findById(id)
            .orElseThrow();

    user.setName(name);
}

Metoda save() pozostaje natomiast przydatna podczas tworzenia nowych encji oraz zapisywania encji odłączonych od kontekstu persystencji.

Ostrożnie z operacjami DELETE

Spring Data JPA udostępnia kilka sposobów usuwania danych, które mogą znacząco różnić się zachowaniem.

Przykładowo:

long deleteByActiveFalse();

W przypadku takiej metody Spring Data JPA pobiera pasujące encje, a następnie usuwa je pojedynczo.

Natomiast:

@Modifying
@Query("DELETE FROM User u WHERE u.active = false")
int deleteInactiveUsers();

wykonuje zbiorczą operację DELETE, bez wcześniejszego pobierania wszystkich usuwanych encji.

Drugie rozwiązanie jest zazwyczaj wydajniejsze przy dużej liczbie rekordów, ale pomija mechanizmy cyklu życia encji, takie jak @PreRemove, oraz kaskadowe usuwanie realizowane przez JPA.

Ponadto zbiorcze operacje UPDATE i DELETE nie synchronizują automatycznie obiektów znajdujących się już w kontekście persystencji.

Dlatego wybór odpowiedniej metody powinien zależeć nie tylko od wydajności, ale również od wymaganej logiki biznesowej.

Własne implementacje repozytoriów

Nie wszystkie operacje da się wygodnie zrealizować za pomocą Query Methods, @Query czy Specification.

W bardziej zaawansowanych przypadkach Spring Data JPA pozwala rozszerzyć repozytorium o własną implementację, nazywaną Repository Fragment.

W tym celu można utworzyć dodatkowy interfejs:

public interface CustomUserRepository {

    List<User> findWithCustomCriteria(String value);
}

Następnie przygotować jego implementację:

public class CustomUserRepositoryImpl
        implements CustomUserRepository {

    private final EntityManager entityManager;

    public CustomUserRepositoryImpl(EntityManager entityManager) {
        this.entityManager = entityManager;
    }

    @Override
    public List<User> findWithCustomCriteria(String value) {
        return entityManager.createQuery("""
                SELECT u FROM User u
                WHERE u.name = :value
                """, User.class)
            .setParameter("value", value)
            .getResultList();
    }
}

Na koniec wystarczy rozszerzyć standardowe repozytorium:

public interface UserRepository
        extends JpaRepository<User, Long>,
                CustomUserRepository {
}

Spring Data JPA połączy standardową implementację repozytorium z własnym fragmentem.

Zaprezentowane zapytanie jest celowo proste. W praktyce takie rozwiązanie ma sens przede wszystkim wtedy, gdy potrzebna jest bardziej rozbudowana logika budowania lub wykonywania zapytań, której nie warto umieszczać bezpośrednio w interfejsie repozytorium.

Kiedy Spring Data JPA nie jest najlepszym rozwiązaniem?

Spring Data JPA dobrze sprawdza się w aplikacjach, w których większość operacji polega na zarządzaniu encjami i wykonywaniu typowych operacji CRUD.

Nie zawsze jednak jest to najlepszy wybór.

Przykładowo, w przypadku:

  • Bardzo rozbudowanych zapytań analitycznych i raportowych.
  • Masowych aktualizacji lub przetwarzania milionów rekordów.
  • Operacji wymagających precyzyjnej kontroli nad generowanym SQL.
  • Aplikacji wykorzystujących zaawansowane funkcjonalności konkretnego silnika bazy danych.

warto rozważyć alternatywne rozwiązania, takie jak Spring JDBC, JdbcTemplate lub inne oparte o native query.

Podsumowanie

Spring Data JPA znacząco upraszcza implementację warstwy dostępu do danych w aplikacjach Java. Dzięki automatycznie generowanym repozytoriom, Query Methods oraz adnotacji @Query pozwala wykonywać większość typowych operacji na bazie danych bez konieczności samodzielnego implementowania DAO.

Mechanizmy takie jak Pageable czy projekcje zapewniają dodatkową elastyczność, umożliwiając efektywne pobieranie danych i budowanie dynamicznych zapytań. Z kolei auditing pozwala automatycznie rejestrować podstawowe informacje o tworzeniu i modyfikowaniu encji.

Warto jednak pamiętać, że Spring Data JPA jest jedynie warstwą abstrakcji nad JPA i nie zastępuje Hibernate. Znajomość mechanizmów takich jak dirty checking, zarządzanie kontekstem persystencji czy lazy loading nadal pozostaje niezbędna do tworzenia wydajnych aplikacji.

Spring Data JPA najlepiej sprawdza się wtedy, gdy jego wygoda idzie w parze ze świadomym korzystaniem z mechanizmów JPA i kontrolą generowanych zapytań SQL.

Źródła:

1. Spring Data JPA – oficjalna dokumentacja
https://docs.spring.io/spring-data/jpa/reference/

2. Spring Data JPA – Repozytoria i generowanie zapytań
https://docs.spring.io/spring-data/jpa/reference/jpa/query-methods.html

3. Spring Data JPA – Paginacja, sortowanie i projekcje
https://docs.spring.io/spring-data/jpa/reference/repositories/projections.html

4. Spring Data JPA – Specifications i dynamiczne zapytania
https://docs.spring.io/spring-data/jpa/reference/jpa/specifications.html

Dodaj komentarz