Spring Boot to jedno z najpopularniejszych narzędzi wykorzystywanych do tworzenia aplikacji w Javie. Bazuje na Spring Framework, ale znacząco upraszcza konfigurację, zarządzanie zależnościami oraz uruchamianie aplikacji. Dzięki mechanizmom takim jak Auto-Configuration czy Spring Boot Starters programista może skupić się na implementacji logiki biznesowej, zamiast na przygotowywaniu infrastruktury projektu.
W tym artykule wyjaśnię, czym jest Spring Boot, jak działa jego mechanizm autokonfiguracji oraz w jaki sposób tworzyć i uruchamiać aplikacje. Przykłady bedą operate na wersji Spring Boot 4.
- Czym jest Spring Boot?
- Tworzenie projektu Spring Boot
- Jak działa Spring Boot?
- Spring Boot Starters – zarządzanie zależnościami
- Mechanizm autokonfiguracji
- Konfiguracja aplikacji Spring Boot
- Profile w Spring Boot
- Wbudowany serwer aplikacyjny
- Spring Boot Actuator – monitorowanie aplikacji
- Budowanie i uruchamianie aplikacji Spring Boot
- Podsumowanie
Czym jest Spring Boot?
Spring Boot to projekt należący do ekosystemu Spring, którego głównym zadaniem jest uproszczenie tworzenia, konfigurowania i uruchamiania aplikacji napisanych w Javie. Bazuje na Spring Framework i dostarcza zestaw gotowych mechanizmów, dzięki którym programista może skupić się na implementacji logiki biznesowej, zamiast na ręcznej konfiguracji infrastruktury aplikacji.
Spring Framework a Spring Boot
Spring Framework dostarcza podstawowych mechanizmów potrzebnych do budowania aplikacji, jednak wiele elementów infrastruktury wymaga odpowiedniej konfiguracji.
Spring Boot upraszcza ten proces poprzez:
- Auto-configuration – automatyczne konfigurowanie komponentów na podstawie bibliotek dostępnych w projekcie i istniejącej konfiguracji.
- Starters – gotowe zestawy zależności, które ułatwiają integrację z określonymi technologiami.
- Embedded server – możliwość uruchamiania aplikacji webowej z wbudowanym serwerem, np. Tomcat, bez konieczności osobnego instalowania i konfigurowania serwera aplikacyjnego.
- Externalized configuration – możliwość zarządzania konfiguracją za pomocą plików
application.properties,application.yml, zmiennych środowiskowych czy argumentów uruchomieniowych. - Production-ready features – mechanizmy monitorowania i diagnostyki aplikacji, udostępniane m.in. przez Spring Boot Actuator.
Dzięki temu aplikacja wykorzystująca Spring Boot może zostać uruchomiona jako samodzielny proces Java, np. za pomocą polecenia java -jar application.jar.
Convention over Configuration
Jedną z najważniejszych zasad, na których opiera się Spring Boot, jest Convention over Configuration, czyli przedkładanie przyjętych konwencji nad konieczność ręcznego definiowania konfiguracji.
Oznacza to, że Spring Boot dostarcza domyślne ustawienia dla wielu popularnych rozwiązań, eliminując potrzebę ich samodzielnego konfigurowania.
Przykładowo, jeśli dodamy do projektu odpowiedni starter Spring MVC, Spring Boot może automatycznie:
- skonfigurować mechanizmy obsługi żądań HTTP,
- uruchomić wbudowany serwer Tomcat,
- skonfigurować niezbędne komponenty Spring MVC.
Programista nadal ma możliwość nadpisania ustawień domyślnych, jeśli wymagają tego potrzeby aplikacji.
Ta notka będzie się opierać na Spring Boot w wersji 4.
Tworzenie projektu Spring Boot
Najprostszym sposobem na utworzenie aplikacji Spring Boot jest skorzystanie z Spring Initializr – narzędzia dostępnego pod adresem https://start.spring.io, które umożliwia wygenerowanie gotowej struktury projektu wraz z niezbędnymi zależnościami.
Podczas tworzenia projektu możemy określić między innymi:
- Project – narzędzie budowania projektu, np. Maven lub Gradle.
- Language – język programowania, np. Java lub Kotlin.
- Spring Boot – wersję Spring Boot, którą chcemy wykorzystać.
- Group i Artifact – identyfikatory projektu.
- Packaging – wybór rodzaju pliku wykonywalnego, np. JAR lub WAR.
- Java – wersję języka.
Dodatkowo możemy wybrać zależności, które zostaną automatycznie dodane do projektu. W naszym przypadku wystarczy Spring Web, umożliwiający tworzenie aplikacji webowych i REST API.
W moim przypadku wybrałem projetk oparty o narzędzie maven, który będzie kompilował sie w języku Java.
Po wygenerowaniu i rozpakowaniu projektu otrzymamy strukturę podobną do poniższej:
src/
├── main/
│ ├── java/
│ │ └── com/example/demo/
│ │ └── DemoApplication.java
│ └── resources/
│ └── application.properties
└── test/
└── java/
└── com/example/demo/
└── DemoApplicationTests.java
pom.xml
mvnw
mvnw.cmdNajważniejsze elementy projektu to:
DemoApplication.java– główna klasa odpowiedzialna za uruchomienie aplikacji.application.properties– plik zawierający konfigurację aplikacji.pom.xml– plik definiujący zależności i konfigurację Mavena.mvnwimvnw.cmd– pliki potrzebne dla narzędzia Maven
Konfiguracja Maven
Przyjrzyjmy się uproszczonej zawartości wygenerowanego pliku pom.xml:
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.2</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<properties>
<java.version>21</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
</dependencies>Warto zwrócić uwagę na dwa elementy:
spring-boot-starter-parent – dostarcza domyślną konfigurację Mavena oraz mechanizm zarządzania wersjami zależności. Dzięki temu nie musimy samodzielnie określać wersji większości bibliotek zarządzanych przez Spring Boot.
spring-boot-starter-webmvc – udostępnia zestaw zależności potrzebnych do tworzenia aplikacji wykorzystujących Spring MVC, w tym wbudowany serwer Tomcat.
W Spring Boot 4 wprowadzono bardziej szczegółowy podział starterów. W przypadku Spring MVC zalecany jest spring-boot-starter-webmvc, który zastępuje dotychczasowy spring-boot-starter-web.
Pierwsza aplikacja Spring Boot
Wygenerowany projekt zawiera główną klasę aplikacji:
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}Adnotacja @SpringBootApplication identyfikuje główną klasę konfiguracyjną aplikacji i uruchamia mechanizmy Spring Boot, w tym automatyczną konfigurację oraz skanowanie komponentów.
Z kolei metoda SpringApplication.run() odpowiada za uruchomienie aplikacji i zainicjalizowanie kontekstu Spring.
Dodajmy teraz prosty kontroler:
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello() {
return "Hello Spring Boot 4!";
}
}Adnotacja @RestController oznacza klasę jako kontroler obsługujący żądania HTTP, natomiast @GetMapping mapuje żądania GET na konkretną metodę.
Aby uruchomić aplikację, wystarczy wykonać:
./mvnw spring-boot:run
Po uruchomieniu Spring Boot automatycznie skonfiguruje i uruchomi wbudowany serwer Tomcat, domyślnie nasłuchujący na porcie 8080.
Po przejściu pod adres:
http://localhost:8080/hello
otrzymamy odpowiedź:
Hello Spring Boot 4!
W ten sposób stworzyliśmy pierwszą aplikację Spring Boot 4, bez konieczności ręcznego konfigurowania serwera HTTP czy infrastruktury Spring MVC.
Jak działa Spring Boot?
W poprzednim rozdziale stworzyliśmy pierwszą aplikację Spring Boot. Przyjrzyjmy się teraz mechanizmom odpowiedzialnym za jej uruchomienie.
Punktem wejścia jest standardowa metoda main():
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}Pomimo niewielkiej ilości kodu, podczas uruchamiania wykonywanych jest wiele operacji, takich jak przygotowanie konfiguracji, utworzenie kontekstu Spring, rejestracja beanów oraz uruchomienie serwera HTTP.
Adnotacja @SpringBootApplication
@SpringBootApplication jest główną adnotacją wykorzystywaną w aplikacjach Spring Boot. Łączy funkcjonalności trzech innych adnotacji:
@SpringBootConfiguration– wskazuje, że klasa jest źródłem konfiguracji Spring. Jest wyspecjalizowaną wersją@Configuration.@EnableAutoConfiguration– włącza mechanizm automatycznej konfiguracji Spring Boot, który dostosowuje konfigurację aplikacji na podstawie dostępnych zależności oraz zdefiniowanych ustawień.@ComponentScan– umożliwia automatyczne wyszukiwanie i rejestrowanie komponentów Spring, takich jak@Component,@Service,@Repositoryczy@Controller.
Oznacza to, że poniższe konfiguracje są zasadniczo równoważne:
@SpringBootApplication
public class DemoApplication {
}oraz:
@SpringBootConfiguration
@EnableAutoConfiguration
@ComponentScan
public class DemoApplication {
}Domyślnie @ComponentScan przeszukuje pakiet, w którym znajduje się klasa oznaczona @SpringBootApplication, oraz jego podpakiety.
Dlatego zaleca się umieszczanie głównej klasy aplikacji w pakiecie nadrzędnym względem pozostałych komponentów.
Przykładowo:
com.example.demo
├── DemoApplication.java
├── controller/
│ └── UserController.java
├── service/
│ └── UserService.java
└── repository/
└── UserRepository.javaW takiej strukturze Spring automatycznie wykryje komponenty znajdujące się we wszystkich wymienionych pakietach, pod warunkiem że zostały oznaczone odpowiednimi adnotacjami.
Metoda SpringApplication.run()
Za uruchomienie aplikacji odpowiada metoda SpringApplication.run().
Jej podstawowym zadaniem jest przygotowanie środowiska wykonawczego oraz utworzenie i zainicjalizowanie kontekstu Spring (ApplicationContext).
Proces uruchamiania można uprościć do następujących etapów:
- Przygotowanie środowiska (
Environment) – odczytanie konfiguracji aplikacji, argumentów uruchomieniowych, zmiennych środowiskowych i aktywnych profili. - Utworzenie
ApplicationContext– wybór i utworzenie odpowiedniego typu kontekstu, zależnie od rodzaju aplikacji. - Rejestracja definicji beanów – przetworzenie klas konfiguracyjnych, skanowanie komponentów oraz zastosowanie mechanizmu autokonfiguracji.
- Inicjalizacja kontekstu – utworzenie i skonfigurowanie beanów, rozwiązanie ich zależności oraz uruchomienie mechanizmów cyklu życia Spring.
- Uruchomienie serwera HTTP – w przypadku aplikacji webowej zainicjalizowanie wbudowanego serwera, np. Tomcat.
- Zakończenie procesu startowego – wykonanie mechanizmów takich jak
CommandLineRunneriApplicationRunner, a następnie zasygnalizowanie gotowości aplikacji.
Metoda SpringApplication.run() zwraca obiekt ConfigurableApplicationContext, który reprezentuje uruchomiony kontekst aplikacji.
Przykładowo:
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
ConfigurableApplicationContext context =
SpringApplication.run(DemoApplication.class, args);
System.out.println(context.getBeanDefinitionCount());
}
}W powyższym przykładzie wyświetlamy liczbę definicji beanów zarejestrowanych w kontekście Spring.
Wbudowany serwer HTTP
Jedną z najważniejszych cech Spring Boot jest możliwość uruchamiania aplikacji webowej bez konieczności instalowania osobnego serwera.
W Spring Boot 4, przy wykorzystaniu spring-boot-starter-webmvc, domyślnie wykorzystywany jest wbudowany serwer Apache Tomcat.
Podczas inicjalizacji kontekstu Spring Boot automatycznie konfiguruje serwer, rejestruje niezbędne komponenty Spring MVC i przygotowuje aplikację do obsługi żądań HTTP.
Domyślnie serwer nasłuchuje na porcie 8080, jednak możemy to zmienić w pliku application.properties:
server.port=9090
Dzięki temu aplikacja będzie dostępna na porcie 9090.
Interfejs CommandLineRunner
Spring Boot udostępnia również mechanizmy pozwalające wykonywać dodatkową logikę podczas uruchamiania aplikacji.
Jednym z nich jest interfejs CommandLineRunner, którego metoda run() wykonywana jest po zainicjalizowaniu kontekstu Spring, ale przed zakończeniem procesu uruchamiania aplikacji.
Przykładowo:
@Component
public class StartupRunner implements CommandLineRunner {
@Override
public void run(String... args) {
System.out.println("Application started!");
}
}Mechanizm ten może służyć np. do inicjalizacji danych lub wykonania określonych operacji startowych.
Spring Boot Starters – zarządzanie zależnościami
Jednym z najważniejszych mechanizmów Spring Boot są Starters, czyli gotowe zestawy zależności pozwalające szybko dodać określoną funkcjonalność do aplikacji.
Zamiast samodzielnie wyszukiwać i dodawać wszystkie potrzebne biblioteki, programista może wykorzystać odpowiedni starter, który dostarcza zestaw kompatybilnych ze sobą zależności.
Jak działają Spring Boot Starters?
Załóżmy, że chcemy utworzyć aplikację REST API wykorzystującą Spring MVC.
W tradycyjnym podejściu należałoby samodzielnie zadbać o zależności związane z obsługą żądań HTTP, serwerem aplikacyjnym czy serializacją danych.
W Spring Boot 4 wystarczy dodać do pom.xml następującą zależność:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>Starter automatycznie pobiera potrzebne biblioteki, między innymi:
- Spring MVC – do obsługi żądań HTTP i tworzenia kontrolerów REST.
- Tomcat – wbudowany serwer aplikacyjny.
- Jackson – do serializacji i deserializacji danych JSON.
- Spring Boot – komponenty wspierające uruchamianie i autokonfigurację aplikacji.
Działa to dzięki mechanizmowi zależności przechodnich (transitive dependencies), obsługiwanemu przez Maven lub Gradle. Dodanie jednego startera powoduje pobranie również bibliotek, od których jest on zależny, bez konieczności deklarowania ich wszystkich w projekcie.
Co istotne, starter nie jest mechanizmem autokonfiguracji samym w sobie. Dostarcza odpowiednie biblioteki, natomiast Spring Boot na podstawie ich obecności oraz ustawień aplikacji może automatycznie skonfigurować potrzebne komponenty
Spring Boot udostępnia wiele gotowych starterów przeznaczonych do różnych zastosowań.
Zarządzanie wersjami zależności
Spring Boot nie tylko ułatwia dodawanie bibliotek, ale również zarządza ich wersjami.
W projekcie Maven wygenerowanym przez Spring Initializr znajdziemy następującą konfigurację:
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.0.9</version>
</parent>spring-boot-starter-parent dostarcza domyślną konfigurację Mavena i wykorzystuje mechanizm Dependency Management.
Dzięki temu nie musimy ręcznie podawać wersji większości bibliotek obsługiwanych przez Spring Boot.
Przykładowo:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
</dependencies>Spring Boot dobiera wersje zależności zgodnie z zestawem zdefiniowanym w spring-boot-dependencies, czyli tzw. BOM (Bill of Materials).
BOM jest plikiem POM zawierającym informacje o wersjach bibliotek, które zostały dobrane i przetestowane pod kątem współpracy z daną wersją Spring Boot.
Dzięki temu aktualizacja Spring Boot pozwala również zaktualizować wiele powiązanych bibliotek, ograniczając ryzyko konfliktów wersji.
Warto pamiętać, że spring-boot-starter-parent nie jest obowiązkowy. Jeśli projekt wykorzystuje własny nadrzędny POM, można zaimportować sam spring-boot-dependencies w sekcji dependencyManagement.
Mechanizm autokonfiguracji
Auto-Configuration to mechanizm, dzięki któremu Spring Boot automatycznie konfiguruje komponenty aplikacji na podstawie dostępnych bibliotek, właściwości konfiguracyjnych oraz beanów.
Przykładowo, jeśli dodamy zależność spring-boot-starter-webmvc, Spring Boot wykryje obecność odpowiednich bibliotek i może automatycznie skonfigurować:
DispatcherServlet, odpowiedzialny za obsługę żądań HTTP w Spring MVC,- mechanizmy mapowania żądań na metody kontrolerów,
- konwertery odpowiedzialne za konwersję danych,
- wbudowany serwer Tomcat.
Spring Boot nie tworzy jednak wszystkich możliwych komponentów. Każda autokonfiguracja może posiadać warunki określające, czy powinna zostać zastosowana.
W tym celu wykorzystywane są między innymi adnotacje @ConditionalOnClass, @ConditionalOnMissingBean i @ConditionalOnProperty.
Adnotacje warunkowe w Spring Boot
@ConditionalOnClass
Adnotacja @ConditionalOnClass sprawdza, czy określona klasa znajduje się na classpath aplikacji.
@ConditionalOnClass(DispatcherServlet.class)
Warunek zostanie spełniony, jeśli klasa DispatcherServlet będzie dostępna w aplikacji, np. dzięki dodaniu startera Spring Web MVC.
W ten sposób Spring Boot może aktywować konfigurację tylko wtedy, gdy odpowiednie biblioteki są obecne.
@ConditionalOnMissingBean
Adnotacja @ConditionalOnMissingBean pozwala utworzyć bean tylko wtedy, gdy Spring nie znalazł wcześniej zarejestrowanego beana określonego typu.
@Bean
@ConditionalOnMissingBean(MessageService.class)
public MessageService messageService() {
return () -> "Hello Spring Boot!";
}Zakładając, że MessageService jest interfejsem z metodą String message(), powyższa konfiguracja utworzy domyślną implementację tylko wtedy, gdy nie został wcześniej zarejestrowany bean tego typu.
Mechanizm ten jest szczególnie ważny w autokonfiguracji, ponieważ umożliwia zastępowanie domyślnych komponentów własnymi implementacjami.
@ConditionalOnBean
Analogicznie o wcześniejszego przypadku @ConditionalOnBean utwórzy bean, tylko wtedy gdy inny bean już istnieje.
@ConditionalOnProperty
Adnotacja @ConditionalOnProperty uzależnia rejestrację beana od wartości określonej właściwości konfiguracyjnej.
@Bean
@ConditionalOnProperty(
prefix = "app.message",
name = "enabled",
havingValue = "true"
)
public MessageService messageService() {
return () -> "Hello Spring Boot!";
}W pliku application.properties można określić:
app.message.enabled=true
Jeśli właściwość przyjmie wartość true, bean zostanie zarejestrowany. W przypadku wartości false nie zostanie utworzony.
Jak sprawdzić działanie autokonfiguracji?
Spring Boot pozwala sprawdzić, które autokonfiguracje zostały zastosowane, a które pominięte.
Wystarczy uruchomić aplikację z parametrem:
./mvnw spring-boot:run -Dspring-boot.run.arguments=--debug
W logach pojawi się raport Conditions Evaluation Report, zawierający informacje o spełnionych i niespełnionych warunkach autokonfiguracji.
Raport jest szczególnie pomocny podczas diagnozowania problemów związanych z brakującymi beanami lub nieoczekiwanym zachowaniem konfiguracji.
Konfiguracja aplikacji Spring Boot
Spring Boot umożliwia zarządzanie konfiguracją aplikacji bez konieczności modyfikowania kodu źródłowego. Parametry takie jak port serwera, adresy zewnętrznych usług, dane dostępowe czy ustawienia połączenia z bazą danych można przechowywać w plikach konfiguracyjnych, zmiennych środowiskowych lub przekazywać podczas uruchamiania aplikacji.
Mechanizm ten nazywany jest Externalized Configuration i pozwala uruchamiać tę samą aplikację w różnych środowiskach, wykorzystując odmienne ustawienia.
application.properties i application.yml
Spring Boot domyślnie odczytuje konfigurację z plików application.properties lub application.yml, które zazwyczaj znajdują się w katalogu src/main/resources.
Przykładowa konfiguracja w formacie Properties:
spring.application.name=demo server.port=8080 app.api-key=test-key app.max-retries=3
Tę samą konfigurację można zapisać w formacie YAML:
spring:
application:
name: demo
server:
port: 8080
app:
api-key: test-key
max-retries: 3Oba formaty oferują te same podstawowe możliwości. YAML jest szczególnie wygodny przy bardziej rozbudowanej konfiguracji, ponieważ umożliwia hierarchiczne grupowanie właściwości.
W przykładzie spring.application.name oraz server.port to właściwości udostępniane przez Spring Boot. Natomiast app.api-key i app.max-retries są własnymi parametrami aplikacji, z których można korzystać w kodzie.
Odczytywanie konfiguracji za pomocą @Value
Najprostszym sposobem pobrania wartości konfiguracyjnej jest wykorzystanie adnotacji @Value.
@Component
public class AppInfo {
@Value("${spring.application.name}")
private String applicationName;
}Spring podczas tworzenia beana odczyta wartość właściwości spring.application.name i przypisze ją do pola applicationName.
Można również określić wartość domyślną:
@Value("${app.max-retries:3}")
private int maxRetries;W tym przypadku, jeśli właściwość app.max-retries nie zostanie zdefiniowana, Spring wykorzysta wartość 3.
Adnotacja @Value sprawdza się przy pojedynczych parametrach, jednak przy większej liczbie ustawień prowadzi do rozproszenia konfiguracji pomiędzy różnymi klasami.
@ConfigurationProperties – mapowanie konfiguracji na obiekty
W przypadku bardziej rozbudowanej konfiguracji lepszym rozwiązaniem jest wykorzystanie adnotacji @ConfigurationProperties.
Pozwala ona automatycznie mapować grupę właściwości na obiekt Javy.
Przykładowo, dla konfiguracji:
app: api-key: test-key max-retries: 3
Można utworzyć rekord:
@ConfigurationProperties(prefix = "app")
public record AppProperties(
String apiKey,
int maxRetries
) {}Spring Boot automatycznie przypisze wartości app.api-key oraz app.max-retries do odpowiednich pól rekordu.
Aby włączyć wyszukiwanie klas oznaczonych @ConfigurationProperties, należy dodać @ConfigurationPropertiesScan do klasy głównej:
@SpringBootApplication
@ConfigurationPropertiesScan
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}Tak zdefiniowaną konfigurację można następnie wstrzykiwać do innych komponentów Spring:
@Service
public class ApiService {
private final AppProperties properties;
public ApiService(AppProperties properties) {
this.properties = properties;
}
public void execute() {
int retries = properties.maxRetries();
// Logika aplikacji
}
}Spring Boot wykorzystuje również mechanizm Relaxed Binding, który pozwala mapować nazwy właściwości zapisane w różnych formatach.
Przykładowo, app.max-retries, app.maxRetries czy app.max_retries mogą zostać powiązane z tym samym polem maxRetries.
W przypadku zmiennych środowiskowych odpowiednikiem app.max-retries jest APP_MAXRETRIES.
Zmienne środowiskowe
Przechowywanie wszystkich parametrów w pliku application.yml nie zawsze jest dobrym rozwiązaniem. Dotyczy to szczególnie poufnych danych, takich jak hasła, tokeny czy klucze API.
Spring Boot umożliwia pobieranie tych wartości bezpośrednio ze zmiennych środowiskowych.
Przykładowo, zamiast umieszczać klucz API w pliku konfiguracyjnym, można wykorzystać placeholder:
app:
api-key: ${APP_API_KEY:}
max-retries: 3Zapis ${APP_API_KEY:} oznacza, że Spring Boot odczyta wartość zmiennej środowiskowej APP_API_KEY. Jeśli zmienna nie istnieje, wykorzysta pusty ciąg znaków.
W systemie Linux zmienną można ustawić poleceniem:
export APP_API_KEY=my-secret-key
Następnie wartość zostanie automatycznie przypisana do pola apiKey w rekordzie AppProperties.
W środowiskach produkcyjnych, np. Kubernetes, zmienne środowiskowe mogą być dostarczane przez konfigurację kontenera lub mechanizmy zarządzania sekretami.
Nadpisywanie konfiguracji
Spring Boot umożliwia definiowanie tych samych właściwości w różnych miejscach. W przypadku konfliktu wykorzystywana jest wartość pochodząca ze źródła o wyższym priorytecie.
Przykładowo, dla typowej aplikacji następujące źródła mają rosnący priorytet:
- Plik
application.ymlumieszczony wewnątrz aplikacji. - Zewnętrzny plik
application.yml. - Zmienne środowiskowe systemu operacyjnego.
- Argumenty przekazywane podczas uruchamiania aplikacji.
Załóżmy, że w pliku application.yml zdefiniowano:
server: port: 8080
Uruchamiając aplikację z parametrem:
java -jar demo.jar --server.port=9090
Sprawimy, że serwer będzie nasłuchiwał na porcie 9090, ponieważ argument uruchomieniowy ma wyższy priorytet niż konfiguracja w pliku.
Analogicznie można wykorzystać zmienną środowiskową SERVER_PORT.
Mechanizm ten jest szczególnie przydatny podczas wdrażania aplikacji, gdy chcemy zmieniać jej konfigurację bez ponownego budowania pliku JAR.
Walidacja konfiguracji – @Validated
Spring Boot umożliwia również walidację wartości konfiguracyjnych podczas uruchamiania aplikacji.
Dzięki temu można wykryć brakujące lub nieprawidłowe parametry, zanim aplikacja zacznie obsługiwać żądania.
W tym celu wykorzystywany jest mechanizm Jakarta Bean Validation.
Najpierw należy dodać odpowiednią zależność:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>Następnie można rozszerzyć wcześniej utworzony rekord AppProperties o adnotacje walidacyjne:
@ConfigurationProperties(prefix = "app")
@Validated
public record AppProperties(
@NotBlank String apiKey,
@Min(1) int maxRetries
) {}W tym przykładzie:
@Validated– uruchamia walidację właściwości konfiguracyjnych.@NotBlank– wymaga, abyapiKeynie był nullem, pustym ciągiem ani ciągiem składającym się wyłącznie z białych znaków.@Min(1)– wymaga, abymaxRetriesmiało wartość nie mniejszą niż1.
Dostępne są również inne adnotacje, takie jak @NotNull, @Max, @Size, @Pattern czy @Email.
Przykładowo, jeśli konfiguracja będzie wyglądała następująco:
app: api-key: "" max-retries: 0
Spring Boot podczas uruchamiania aplikacji spróbuje utworzyć obiekt AppProperties, ale walidacja zakończy się niepowodzeniem.
W logach pojawi się błąd wskazujący nieprawidłowe właściwości, np. app.api-key oraz app.max-retries, a aplikacja nie zostanie uruchomiona.
Warto pamiętać, że walidacja działa również wtedy, gdy dana wartość pochodzi ze zmiennej środowiskowej lub argumentu uruchomieniowego, a nie bezpośrednio z pliku YAML.
Dzięki temu można uniknąć sytuacji, w której aplikacja uruchamia się z nieprawidłową konfiguracją, a problem zostaje wykryty dopiero podczas wykonywania operacji biznesowych.
Profile w Spring Boot
Profile w Spring Boot pozwalają dostosować konfigurację i zachowanie aplikacji do środowiska, w którym jest uruchamiana. Dzięki nim ta sama aplikacja może korzystać z różnych ustawień podczas lokalnego programowania, testowania i działania na produkcji.
Najczęściej wykorzystywane profile to:
- dev – środowisko developerskie, np. lokalna baza danych i szczegółowe logowanie.
- test – środowisko testowe, np. testowa baza danych i zewnętrzne serwisy zastąpione atrapami.
- prod – środowisko produkcyjne, np. rzeczywista baza danych i ograniczony poziom logowania.
Konfiguracja zależna od profilu
Spring Boot umożliwia definiowanie osobnych plików konfiguracyjnych dla poszczególnych środowisk.
Przykładowa struktura projektu:
src/main/resources/ ├── application.yml ├── application-dev.yml └── application-prod.yml
W pliku application.yml można umieścić wspólne ustawienia aplikacji:
spring:
application:
name: demo
server:
port: 8080Natomiast w application-dev.yml konfigurację dla środowiska developerskiego:
logging:
level:
root: DEBUG
app:
api-url: http://localhost:9090W przypadku środowiska produkcyjnego plik application-prod.yml może wyglądać następująco:
logging:
level:
root: WARN
app:
api-url: https://api.example.comPodczas uruchamiania aplikacji Spring Boot wczytuje konfigurację podstawową oraz pliki odpowiadające aktywnym profilom.
Jeśli aktywny jest profil dev, Spring Boot odczyta zarówno application.yml, jak i application-dev.yml. W przypadku konfliktu wartości z pliku profilowego mają pierwszeństwo przed konfiguracją podstawową.
Adnotacja @Profile
Profile mogą również decydować o tym, które beany zostaną zarejestrowane w kontekście Spring.
Służy do tego adnotacja @Profile.
Załóżmy, że aplikacja korzysta z interfejsu MessageService:
public interface MessageService {
String getMessage();
}Chcemy, aby w zależności od środowiska Spring wykorzystywał inną implementację.
@Configuration
public class MessageConfiguration {
@Bean
@Profile("dev")
public MessageService devMessageService() {
return () -> "Development environment";
}
@Bean
@Profile("prod")
public MessageService prodMessageService() {
return () -> "Production environment";
}
}W zależności od aktywnego profilu Spring zarejestruje odpowiedni bean:
dev– zostanie utworzony beandevMessageService.prod– zostanie utworzony beanprodMessageService.
Jeżeli nie zostanie aktywowany żaden z tych profili, żaden z powyższych beanów nie będzie zarejestrowany. Jeśli natomiast aktywujemy oba profile jednocześnie, zostaną utworzone dwa beany typu MessageService, co może prowadzić do niejednoznaczności podczas wstrzykiwania zależności.
Adnotację @Profile można stosować nie tylko do metod oznaczonych @Bean, ale również do klas konfiguracyjnych i komponentów Spring.
Aktywowanie profili
Spring Boot umożliwia aktywowanie profili na kilka sposobów.
1. W pliku application.yml
spring:
profiles:
active: devTakie ustawienie sprawi, że aplikacja domyślnie uruchomi się z profilem dev.
2. Za pomocą argumentu uruchomieniowego
java -jar demo.jar --spring.profiles.active=prod
Ten sposób pozwala wskazać profil bez konieczności modyfikowania plików konfiguracyjnych.
3. Za pomocą zmiennej środowiskowej
export SPRING_PROFILES_ACTIVE=prod
Spring Boot automatycznie odczyta wartość zmiennej i aktywuje profil prod.
Można również aktywować kilka profili jednocześnie:
java -jar demo.jar --spring.profiles.active=prod,metrics
W takim przypadku aktywne będą profile prod oraz metrics.
Jeśli żaden profil nie zostanie wskazany, Spring wykorzysta profil o nazwie default.
Warto pamiętać, że właściwości spring.profiles.active nie można definiować w plikach specyficznych dla profilu, takich jak application-dev.yml.
Dobre praktyki korzystania z profili
Profile najlepiej wykorzystywać do konfiguracji zależnej od środowiska, np. ustawień logowania, adresów usług czy warunkowej rejestracji komponentów.
Nie powinny natomiast służyć do przechowywania poufnych danych, takich jak hasła czy klucze API. Takie wartości lepiej dostarczać za pomocą zmiennych środowiskowych lub dedykowanych mechanizmów zarządzania sekretami.
Warto również unikać nadmiernego uzależniania logiki biznesowej od profili. Jeśli dwie implementacje różnią się jedynie parametrami, często wystarczy wykorzystać @ConfigurationProperties, zamiast tworzyć osobne klasy dla każdego środowiska.
Wbudowany serwer aplikacyjny
Jedną z zalet Spring Boot jest możliwość uruchamiania aplikacji webowych bez konieczności instalowania i konfigurowania zewnętrznego serwera aplikacyjnego.
W tradycyjnym podejściu aplikacje Java EE/Jakarta EE często były pakowane do plików WAR, które następnie wdrażano na serwerach takich jak Tomcat czy WildFly. Konfiguracja i wdrażanie produkcyjne aplikacji na taki serwer było często męczarnią.
Jednym z największych zalet i jednocześniej przełomów było, to że Spring Boot upraszczał znacznie ten proces, umożliwiając uruchomienie aplikacji bezpośrednio za pomocą metody main().
Embedded Tomcat – jak działa?
Spring Boot domyślnie wykorzystuje wbudowany serwer Tomcat w aplikacjach opartych na Spring MVC.
Dodanie zależności spring-boot-starter-webmvc powoduje dołączenie bibliotek niezbędnych do uruchomienia aplikacji webowej, w tym serwera Tomcat.
Podczas wywołania:
SpringApplication.run(DemoApplication.class, args);
Spring Boot inicjalizuje kontekst aplikacji i uruchamia wbudowany serwer HTTP.
W uproszczeniu obsługa żądania wygląda następująco:
- Tomcat odbiera żądanie HTTP od klienta.
- Żądanie trafia do
DispatcherServlet, który jest centralnym komponentem Spring MVC. DispatcherServletprzekazuje żądanie do odpowiedniego kontrolera.- Kontroler przetwarza żądanie i zwraca odpowiedź.
- Tomcat odsyła odpowiedź HTTP do klienta.
JAR a WAR – dwa sposoby uruchamiania aplikacji
Aplikacje Spring Boot można pakować zarówno do plików JAR, jak i WAR. W przypadku Spring Boot najczęściej wykorzystuje się pliki JAR, ponieważ pozwalają uruchomić aplikację jako samodzielny proces.
Pliki WAR nadal są wspierane. Aby przygotować aplikację do tradycyjnego wdrożenia, należy odpowiednio skonfigurować pakowanie, zależności serwera oraz wykorzystać SpringBootServletInitializer.
Konfiguracja serwera w Spring Boot
Spring Boot pozwala konfigurować wbudowany serwer za pomocą właściwości w pliku application.yml.
Przykładowa konfiguracja:
server:
port: 9090
servlet:
context-path: /api
tomcat:
threads:
max: 200Poszczególne właściwości oznaczają:
server.port– port HTTP, na którym nasłuchuje aplikacja. Domyślnie8080.server.servlet.context-path– główna ścieżka kontekstowa aplikacji.server.tomcat.threads.max– maksymalna liczba wątków roboczych Tomcata przy standardowym modelu obsługi żądań. Ustawienie to nie ma zastosowania, gdy włączono obsługę wirtualnych wątków.
Jeżeli wcześniej utworzony kontroler obsługuje endpoint /api/hello, po zastosowaniu powyższej konfiguracji będzie dostępny pod adresem:
http://localhost:9090/api/api/hello
Spring Boot Actuator – monitorowanie aplikacji
Spring Boot Actuator to moduł umożliwiający monitorowanie i zarządzanie działającą aplikacją. Udostępnia informacje o jej stanie, wykorzystaniu zasobów, metrykach wydajnościowych oraz konfiguracji.
Jest szczególnie przydatny w środowiskach produkcyjnych, gdzie aplikacje muszą być stale monitorowane, a ewentualne problemy powinny być szybko wykrywane.
Jak włączyć Spring Boot Actuator?
Aby skorzystać z Actuatora, wystarczy dodać do pom.xml następującą zależność:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>Spring Boot automatycznie skonfiguruje mechanizmy Actuatora i udostępni odpowiednie endpointy.
Domyślnie endpointy HTTP znajdują się pod ścieżką /actuator. Przykładowo, przy standardowej konfiguracji serwera na porcie 8080, stan aplikacji można sprawdzić pod adresem:
GET http://localhost:8080/actuator/health
Ze względów bezpieczeństwa domyślnie przez HTTP udostępniany jest wyłącznie endpoint health. Pozostałe endpointy należy jawnie udostępnić w konfiguracji.
Najważniejsze endpointy Actuatora
Spring Boot Actuator oferuje wiele gotowych endpointów diagnostycznych.
| Endpoint | Zastosowanie |
|---|---|
/actuator/health | Informacje o stanie aplikacji |
/actuator/info | Podstawowe informacje o aplikacji |
/actuator/metrics | Metryki aplikacji i JVM |
/actuator/beans | Lista beanów zarejestrowanych w kontekście Spring |
/actuator/env | Informacje o właściwościach środowiskowych |
/actuator/loggers | Podgląd i zmiana poziomów logowania |
/actuator/conditions | Raport działania mechanizmu autokonfiguracji |
Aby udostępnić wybrane endpointy, można dodać następującą konfigurację do application.yml:
management:
endpoints:
web:
exposure:
include: health,info,metricsW rezultacie Spring Boot udostępni trzy endpointy: health, info oraz metrics.
Endpoint health – stan aplikacji
Endpoint /actuator/health pozwala sprawdzić, czy aplikacja działa prawidłowo.
Przykładowa odpowiedź:
{
"status": "UP"
}Status UP oznacza, że aplikacja jest uznawana za działającą prawidłowo na podstawie skonfigurowanych mechanizmów kontroli stanu.
Spring Boot może automatycznie sprawdzać również dostępność zależności, takich jak baza danych, Redis czy RabbitMQ.
Weryfikacja odbywa się za pomocą komponentów implementujących interfejs HealthIndicator.
Domyślnie szczegóły kontroli stanu nie są widoczne. Można je włączyć za pomocą właściwości:
management:
endpoint:
health:
show-details: alwaysPrzykładowa odpowiedź może wtedy wyglądać następująco:
{
"status": "UP",
"components": {
"db": {
"status": "UP"
},
"diskSpace": {
"status": "UP"
},
"ping": {
"status": "UP"
}
}
}W tym przykładzie wszystkie sprawdzane komponenty działają prawidłowo.
Jeżeli np. baza danych przestanie odpowiadać, jej status może zmienić się na DOWN, co może również wpłynąć na ogólny status aplikacji.
W środowisku produkcyjnym należy jednak unikać publicznego udostępniania szczegółowych informacji diagnostycznych.
Endpoint info – informacje o aplikacji
Endpoint /actuator/info umożliwia udostępnianie informacji o aplikacji, takich jak jej nazwa, wersja czy numer commita.
Przykładowa konfiguracja:
management:
info:
env:
enabled: true
info:
app:
name: Demo Application
version: 1.0.0
description: Spring Boot examplePo udostępnieniu endpointu info i jego wywołaniu:
GET http://localhost:8080/actuator/info
Otrzymamy odpowiedź:
{
"app": {
"name": "Demo Application",
"version": "1.0.0",
"description": "Spring Boot example"
}
}Warto zwrócić uwagę na właściwość management.info.env.enabled=true, która włącza publikowanie informacji z sekcji info konfiguracji aplikacji.
Spring Boot umożliwia również automatyczne udostępnianie informacji o procesie budowania aplikacji oraz repozytorium Git.
Endpoint metrics – metryki aplikacji
Endpoint /actuator/metrics pozwala przeglądać metryki dotyczące działania aplikacji.
Spring Boot wykorzystuje w tym celu bibliotekę Micrometer, która zapewnia wspólny interfejs do zbierania metryk i integracji z systemami monitoringu.
Po wywołaniu:
GET http://localhost:8080/actuator/metrics
Otrzymamy listę dostępnych metryk. Przykładowo:
| Metryka | Zastosowanie |
|---|---|
jvm.memory.used | Ilość pamięci wykorzystywanej przez JVM |
jvm.gc.pause | Czas pauz związanych z Garbage Collectorem |
jvm.threads.live | Liczba aktywnych wątków JVM |
process.cpu.usage | Wykorzystanie CPU przez proces |
http.server.requests | Statystyki obsługi żądań HTTP |
Dostępność poszczególnych metryk zależy od konfiguracji aplikacji i wykorzystywanych bibliotek.
Można również sprawdzić konkretną metrykę:
GET http://localhost:8080/actuator/metrics/jvm.memory.used
Endpoint zwróci informacje o wykorzystaniu pamięci JVM, w tym wartość pomiaru i dostępne tagi.
Actuator umożliwia nie tylko odczytywanie gotowych metryk, ale również definiowanie własnych za pomocą Micrometera.
W środowiskach produkcyjnych metryki często zbierane są przez Prometheus, a następnie prezentowane na dashboardach w Grafanie. Integracja z Prometheus wymaga dodatkowej zależności micrometer-registry-prometheus.
Budowanie i uruchamianie aplikacji Spring Boot
Spring Boot umożliwia zbudowanie aplikacji w postaci samodzielnego pliku JAR, który można uruchomić bez konieczności instalowania zewnętrznego serwera aplikacyjnego.
Do budowania aplikacji można wykorzystać Maven lub Gradle. W poniższych przykładach skupię się na Mavenie.
Spring Boot Maven Plugin
Spring Boot udostępnia wtyczkę spring-boot-maven-plugin, która integruje się z Mavenem i umożliwia między innymi tworzenie wykonywalnych plików JAR oraz uruchamianie aplikacji.
Aby z niej skorzystać, należy dodać do pom.xml następującą konfigurację:
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>Jeśli projekt korzysta z spring-boot-starter-parent, nie trzeba dodatkowo konfigurować wykonywania zadania repackage. Spring Boot dostarcza odpowiednie ustawienia domyślne.
repackage to zadanie odpowiedzialne za przekształcenie standardowego archiwum JAR w plik umożliwiający samodzielne uruchomienie aplikacji wraz z wymaganymi zależnościami.
Tworzenie wykonywalnego pliku JAR
Aby zbudować aplikację, wystarczy wykonać polecenie:
./mvnw clean package
Maven przeprowadzi kompilację kodu źródłowego, uruchomi testy i przygotuje plik JAR.
Po pomyślnym zakończeniu procesu w katalogu target pojawi się plik, np.:
target/demo-0.0.1-SNAPSHOT.jar
W przeciwieństwie do zwykłego archiwum JAR, wykonywalny JAR Spring Boot zawiera nie tylko skompilowane klasy aplikacji, ale również biblioteki niezbędne do jej uruchomienia.
Przykładowa struktura archiwum:
demo-0.0.1-SNAPSHOT.jar ├── META-INF/ ├── BOOT-INF/ │ ├── classes/ │ └── lib/ └── org/springframework/boot/loader/
Najważniejsze katalogi:
BOOT-INF/classes– skompilowane klasy aplikacji i jej zasoby.BOOT-INF/lib– biblioteki wykorzystywane przez aplikację.org/springframework/boot/loader– klasy odpowiedzialne za uruchamianie aplikacji z tak przygotowanego archiwum.
Takie rozwiązanie jest często określane jako Fat JAR lub Executable JAR.
Uruchamianie aplikacji za pomocą java -jar
Po zbudowaniu projektu aplikację można uruchomić poleceniem:
java -jar target/demo-0.0.1-SNAPSHOT.jar
Spring Boot zainicjalizuje kontekst Spring, utworzy wymagane beany oraz uruchomi wbudowany serwer HTTP, jeśli aplikacja jest aplikacją webową.
Istnieje również możliwość uruchomienia projektu bez wcześniejszego budowania pliku JAR:
./mvnw spring-boot:run
To rozwiązanie jest szczególnie wygodne podczas lokalnego programowania.
Podsumowanie
Spring Boot znacząco upraszcza tworzenie i rozwijanie aplikacji opartych na Spring Framework. Dzięki gotowym starterom, automatycznej konfiguracji oraz wbudowanemu serwerowi pozwala ograniczyć ilość konfiguracji niezbędnej do uruchomienia projektu.
Jednocześnie oferuje rozbudowane możliwości zarządzania ustawieniami aplikacji, obsługę różnych środowisk za pomocą profili oraz narzędzia do monitorowania działania systemu, takie jak Spring Boot Actuator.
Warto jednak pamiętać, że automatyzacja nie zastępuje znajomości mechanizmów Spring Framework. Zrozumienie działania kontekstu aplikacji, zarządzania beanami i autokonfiguracji pozwala skuteczniej diagnozować problemy oraz świadomie dostosowywać Spring Boot do potrzeb projektu.
Źródło:
Spring Boot – Auto-configuration
https://docs.spring.io/spring-boot/4.0/reference/using/auto-configuration.html
Spring Boot – Build Systems
https://docs.spring.io/spring-boot/4.0/reference/using/build-systems.html
Spring Boot – Externalized Configuration.
https://docs.spring.io/spring-boot/4.0/reference/features/external-config.html
Spring Boot – Actuator Endpoints
https://docs.spring.io/spring-boot/4.0/reference/actuator/endpoints.html
