Spring Boot compatibility matrix jak sprawdzić zgodność z Javą i bibliotekami
- Gdzie znajdziesz spring boot compatibility matrix i jak ją czytać
- Jak dobrać wersję Javy do Spring Boot
- Jak sprawdzić zgodność Spring Boot z Spring Framework i bibliotekami
- Co sprawdzić w pliku pom.xml i build.gradle
- Jak przetestować zgodność przed wdrożeniem
- Jakie błędy popełnia się przy aktualizacji Spring Boot
- Najczęstsze pytania
Spring Boot compatibility matrix to tabela zgodności, która pokazuje, z którą wersją Javy, Spring Framework i bibliotek działa dana wersja Spring Boot. Sprawdzasz ją w oficjalnej dokumentacji w sekcji System Requirements i w dokumentacji zależności. Najkrótsza reguła: Spring Boot 3.x wymaga Javy 17 lub nowszej, a Spring Boot 2.7 obsługuje Javę 8 i wybrane nowsze wersje.
Gdzie znajdziesz spring boot compatibility matrix i jak ją czytać
Oficjalna „spring boot compatibility matrix” nie jest jednym plikiem pod stałym adresem. Dla każdej wersji Spring Boot dokumentacja podaje sekcję System Requirements. Tam sprawdzisz minimalną i maksymalną wersję Javy, wymagania Maven i Gradle oraz wersję Spring Framework. Wejdź na oficjalną dokumentację Spring Boot, wybierz konkretną wersję, np. 3.4.x, i otwórz rozdział System Requirements. Potem zajrzyj do release notes i do dokumentacji bibliotek, których używasz.
To ma znaczenie, bo tabela dla Spring Boot 3.4 może wyglądać inaczej niż dla 3.2. Sprawdzając najnowszą wersję Spring Boot, nie zakładaj, że najnowsza Java jest zawsze wspierana. Spring Boot zwykle dopuszcza nowszą Javę dopiero po wydaniu kolejnej linii. Górna granica zmienia się przy każdym wydaniu, więc data publikacji dokumentacji ma znaczenie.
Przykładowe zestawienie, które spotkasz w dokumentacji:
| Wersja Spring Boot | Wersja Javy | Spring Framework | Co to oznacza w praktyce |
|---|---|---|---|
| 2.7.x | 8-21 | 5.3.x | Ostatnia linia 2.x. Publiczne wsparcie OSS zakończyło się w listopadzie 2023 r. |
| 3.0.x | 17-19 | 6.0.x | Przejście na Jakarta EE 9 i koniec z javax. |
| 3.1.x | 17-20 | 6.0.x | Java 17 nadal jest minimum. |
| 3.2.x | 17-21 | 6.1.x | Java 21 wchodzi do oficjalnego wsparcia. |
| 3.3.x | 17-22 | 6.1.x | Sprawdź release notes bibliotek. |
| 3.4.x | 17-23 | 6.2.x | Górna granica rośnie wraz z kolejnymi wydaniami. |
Ta tabela pomaga szybko odrzucić oczywiste błędy, ale nie zastępuje testów. biblioteka może mieć zapisane wsparcie dla Javy 21, a mimo to nie działać z twoją konfiguracją. Dlatego po sprawdzeniu dokumentacji uruchom projekt na docelowym JDK.

Jak dobrać wersję Javy do Spring Boot
Minimalna wersja Javy to jedno, a docelowa wersja w projekcie to drugie. Jeśli kompilujesz pod Javę 11, nie przeskoczysz na Spring Boot 3. Ta linia wymaga Javy 17 co najmniej. Jeśli masz Javę 8, możesz zostać na Spring Boot 2.7 albo zaplanować migrację. Innej opcji nie ma.
Java 21 jest wspierana od Spring Boot 3.2. Java 22 od 3.3, a Java 23 od 3.4. Kolejne wersje Javy wchodzą do wsparcia razem z nowymi liniami Spring Boot. Gdy planujesz przeskok, sprawdź najnowszy Spring Boot i które wydanie obsługuje twoją Javę. Nie ustawiaj java.version na 21 tylko dlatego, że masz taki JDK na komputerze. Sprawdź, czy build i runtime używają tej samej wersji.
W Maven ustaw <java.version>17</java.version> albo maven.compiler.release. W Gradle użyj java.toolchain i wskaż konkretny JDK. Dzięki temu build nie zależy od tego, co masz ustawione w JAVA_HOME. W CI dodaj macierz z Javą 17 i 21, a przy najnowszych wersjach Spring Boot także z kolejnym JDK.
Jak sprawdzić zgodność Spring Boot z Spring Framework i bibliotekami
Spring Boot parent albo BOM zarządza wersjami Spring Framework, Jacksona, Hibernate, Tomcat, JUnit i wielu innych bibliotek. Jeśli zastanawiasz się, czym się różni Spring od Spring Boot, pamiętaj, żeby nie nadpisywać spring-core bez powodu. Ręczne ustawienie wersji Spring Framework często kończy się konfliktem, którego nie widać na pierwszy rzut oka. Najpierw sprawdź, czy problem naprawdę wymaga zmiany wersji.
Spring Cloud ma własną tabelę zgodności. Dla Spring Boot 3.2 użyj Spring Cloud 2023.0.x, dla 3.4 linię 2024.0.x. Spring Boot 2.7 współpracuje ze Spring Cloud 2021.0.x. To nie są luźne sugestie, bo Spring Cloud opiera się na konkretnych mechanizmach Spring Boota. Aktualizacja samego Boota bez Spring Cloud może wyłączyć konfigurację albo wysypać testy integracyjne.
Biblioteki trzecie też mają granice. Spring Boot 3 korzysta z Hibernate 6 i przestrzeni jakarta.*. Stary filtr oparty na javax.servlet nie zadziała. Lombok i MapStruct muszą wspierać docelową Javę, zwłaszcza gdy używają przetwarzania adnotacji. Flyway, sterowniki baz danych i klienty HTTP sprawdź w ich dokumentacji, bo sama zgodność z Javą nie gwarantuje zgodności ze Spring Bootem.
Co sprawdzić w pliku pom.xml i build.gradle
W Maven otwórz pom.xml i sprawdź <parent> z spring-boot-starter-parent. Jeśli nie używasz parenta, sprawdź import BOM spring-boot-dependencies. Wersja Spring Boot powinna być jedna dla całego projektu. Jeśli chcesz śledzić Spring Boot current version w wielu modułach, sprawdź parent w katalogu głównym. W Gradle zobaczysz ją w bloku plugins przy org.springframework.boot. Nie mieszaj BOM Spring Boota z ręcznym ustawianiem wersji Spring Framework.
Uruchom ./mvnw dependency:tree -Dverbose i poszukaj konfliktów. Zawęź wynik do konkretnej biblioteki, np. ./mvnw dependency:tree -Dincludes=org.springframework:spring-core. W Gradle użyj ./gradlew dependencies --configuration runtimeClasspath albo ./gradlew dependencyInsight --dependency spring-core --configuration runtimeClasspath. Te polecenia pokażą, która zależność ciągnie starą wersję.
Dodaj Maven Enforcer Plugin, jeśli chcesz blokować niechciane zależności. Reguła bannedDependencies przyda się przy zakazie javax.servlet:javax.servlet-api. W Gradle możesz użyć resolutionStrategy albo constraints. Traktuj „spring boot compatibility matrix” jako punkt wyjścia, a rzeczywisty stan projektu sprawdzaj w drzewie zależności. Dokumentacja podaje intencje, a build pokazuje fakty.
Jak przetestować zgodność przed wdrożeniem
Nie wystarczy kompilacja. Uruchom aplikację na docelowym JDK i wykonaj pełne testy. W CI dodaj macierz z Javą 17, 21 i najnowszą wersją wspieraną przez twoją linię Spring Boot. Komenda ./mvnw verify albo ./gradlew build powinna przejść na każdym JDK. Jeśli testy integracyjne używają Testcontainers, sprawdź także wersję Dockera i obrazów baz danych.
Zajrzyj do konfiguracji obrazu kontenera. spring-boot-maven-plugin buduje obraz na podstawie wybranego JRE. Jeśli aplikacja działa na Javie 21, obraz nie może mieć Javy 17. Sprawdź też sourceCompatibility i targetCompatibility, bo stare wpisy potrafią zostać w projekcie po migracji. Przy problemach z bytecode użyj javap -verbose i sprawdź wartość major version.
Przetestuj start aplikacji, migracje Flyway, bezpieczeństwo i klienty HTTP. Najczęstsze błędy wychodzą dopiero przy połączeniu z bazą albo przy deserializacji JSON. Uruchom też testy na profilu zbliżonym do produkcji. Zgodność wersji to warunek startu, a nie gwarancja, że cały stos zadziała bez testów.

Jakie błędy popełnia się przy aktualizacji Spring Boot
Najczęstszy błąd to zostawienie javax.* po przejściu na Spring Boot 3. Kompilator pokaże część problemów, ale stare zależności mogą ciągnąć nieaktualne API. Drugi błąd to ręczne nadpisanie wersji Spring Framework. Trzeci to aktualizacja Spring Boota bez dopasowania Spring Cloud. Każdy z tych przypadków potrafi zająć godziny.
Kolejna pułapka to pominięcie przetwarzania adnotacji. Lombok, MapStruct i inne generatory kodu muszą działać z docelową Javą. Jeśli testujesz tylko na JDK dewelopera, błąd wyjdzie na produkcji. Czytaj release notes przed aktualizacją, zwłaszcza gdy przeskakujesz kilka wersji. Migracja z 2.7 do 3.x wymaga osobnego planu, bo zmian jest więcej niż w numerze wersji.
Najczęstsze pytania
Jaka wersja Javy jest wymagana dla Spring Boot 3?
Spring Boot 3.0 i nowsze wymagają co najmniej Javy 17. To twarde wymaganie, bo Spring Boot 3 opiera się na Spring Framework 6 i Jakarta EE 9. Java 8 i 11 nie zadziałają. Górna granica zależy od wersji Spring Boot, np. 3.2 wspiera Javę 21, a 3.4 Javę 23. Sprawdź System Requirements dla dokładnej wersji, której chcesz użyć.
Czy Spring Boot 2.7 działa z Java 17?
Tak, Spring Boot 2.7 działa z Javą 17, a według dokumentacji jest zgodny także z nowszymi wersjami do Javy 21. To nadal linia 2.x, więc nie dostaje nowych funkcji i publiczne wsparcie OSS zakończyło się w 2023 r. Jeśli zostajesz na Javie 17, lepszym kierunkiem jest migracja do Spring Boot 3.x.
Gdzie sprawdzić zgodność Spring Boot z bibliotekami?
Najpierw zajrzyj do System Requirements dla swojej wersji Spring Boot i do release notes. Potem sprawdź dokumentację biblioteki, np. Spring Cloud, Hibernate, Flyway albo Spring Security. W projekcie uruchom mvn dependency:tree lub gradlew dependencies, żeby zobaczyć rzeczywiste wersje. Oficjalna tabela zgodności to punkt wyjścia, nie jedyne źródło.
Czy można używać Spring Boot 3 z javax?
Nie. Spring Boot 3 przeszedł na Jakarta EE 9 i używa przestrzeni nazw jakarta.* zamiast javax.*. Jeśli biblioteka nadal importuje javax.servlet, musisz znaleźć nowszą wersję albo zamiennik. To dotyczy m.in. starych filtrów, serwletów i walidacji. Migracja kodu bywa większa niż sama zmiana numeru wersji Spring Boot.
Jak sprawdzić wersję Spring Boot w projekcie Maven?
Otwórz pom.xml i sprawdź wpis <parent> z spring-boot-starter-parent albo import BOM spring-boot-dependencies. Wersję znajdziesz też komendą ./mvnw help:evaluate -Dexpression=project.parent.version -q -DforceStdout. Jeśli używasz wielu modułów, sprawdź parent w katalogu głównym. W Gradle zobaczysz ją w bloku plugins przy org.springframework.boot.
Czy Spring Boot 3.2 działa z Java 21?
Tak, Spring Boot 3.2 oficjalnie wspiera Javę 21. Minimalna wersja to nadal Java 17, więc możesz zostać na 17 albo przejść na 21. Java 21 daje m.in. virtual threads, ale ich użycie w Spring Boot wymaga konfiguracji i testów. Sprawdź też wersje bibliotek, zwłaszcza Spring Cloud i Hibernate, bo sama Java 21 nie gwarantuje zgodności całego stosu.