Spring MVC – architektura, kontrolery i obsługa żądań HTTP

Spring MVC to jeden z najczęściej wykorzystywanych modułów Spring Framework, stanowiący podstawę wielu współczesnych aplikacji webowych oraz mikroserwisów napisanych w języku Java. Dzięki integracji ze Spring Boot tworzenie REST API jest stosunkowo proste i nie wymaga od programisty szczegółowej znajomości Servlet API. Warto jednak wiedzieć, jakie mechanizmy kryją się za pozornie prostymi adnotacjami, takimi jak @RestController czy @GetMapping.

Spis treści

Czym jest Spring MVC?

Spring MVC (Spring Web MVC) to moduł Spring Framework przeznaczony do tworzenia aplikacji webowych oraz REST API w języku Java. Opiera się na wzorcu architektonicznym MVC (Model-View-Controller) oraz wykorzystuje Servlet API (obecnie Jakarta Servlet API) do obsługi żądań HTTP.

Spring MVC stanowi warstwę webową aplikacji, odpowiadającą za komunikację pomiędzy klientem (np. przeglądarką internetową, aplikacją mobilną lub innym mikroserwisem) a logiką biznesową aplikacji.

Do najważniejszych funkcjonalności Spring MVC należą:

  • mapowanie żądań HTTP na odpowiednie metody kontrolerów,
  • pobieranie i konwertowanie danych przekazywanych przez klienta,
  • serializacja i deserializacja danych, np. w formacie JSON,
  • walidacja danych wejściowych,
  • obsługa wyjątków,
  • obsługa widoków i generowanie stron HTML,
  • wersjonowanie API.

Spring MVC umożliwia tworzenie dwóch podstawowych rodzajów aplikacji:

  • Tradycyjnych aplikacji webowych – w których serwer generuje widoki HTML, np. przy użyciu Thymeleaf.
  • REST API – w których serwer zwraca dane, najczęściej w formacie JSON, przetwarzane następnie przez aplikację kliencką.

W połączeniu ze Spring Boot konfiguracja Spring MVC jest w dużej mierze zautomatyzowana, dzięki czemu programista może skoncentrować się na implementacji logiki aplikacji, zamiast na konfiguracji infrastruktury webowej.

Wzorzec MVC – Model, View, Controller

MVC (Model-View-Controller) to wzorzec architektoniczny, którego głównym założeniem jest rozdzielenie danych aplikacji, sposobu ich prezentacji oraz mechanizmu obsługi żądań użytkownika.

Wzorzec ten dzieli aplikację na trzy podstawowe komponenty:

  • Model – reprezentuje dane wykorzystywane przez aplikację. W Spring MVC model może zawierać obiekty, które kontroler przekazuje do widoku w celu ich wyświetlenia.
  • View (widok) – odpowiada za prezentację danych użytkownikowi, np. w postaci strony HTML wygenerowanej za pomocą Thymeleaf.
  • Controller (kontroler) – odpowiada za obsługę żądań użytkownika, komunikację z warstwą biznesową aplikacji oraz przekazywanie danych do widoku.
spring mvc flow

Główną zaletą wzorca MVC jest separacja odpowiedzialności (Separation of Concerns), która ułatwia rozwijanie, testowanie oraz utrzymywanie poszczególnych elementów aplikacji.

Architektura Spring MVC – DispatcherServlet

Spring MVC opiera się na wzorcu projektowym Front Controller, którego założeniem jest istnienie jednego centralnego komponentu odpowiedzialnego za koordynowanie obsługi żądań HTTP.

W Spring MVC rolę tę pełni DispatcherServlet.

DispatcherServlet

DispatcherServlet to servlet stanowiący centralny punkt wejścia dla żądań HTTP obsługiwanych przez Spring MVC. Odpowiada za przekierowanie żądania do odpowiedniego kontrolera, a następnie przygotowanie odpowiedzi HTTP przy współpracy z pozostałymi komponentami frameworka.

Sam DispatcherServlet nie implementuje logiki biznesowej aplikacji. Jego zadaniem jest koordynowanie pracy innych komponentów. Servlet to komponent aplikacji webowej napisany w języku Java, działający po stronie serwera, którego zadaniem jest obsługa żądań klientów i generowanie odpowiedzi, najczęściej z wykorzystaniem protokołu HTTP.

Przeanalizujmy przebieg żądania HTTP na przykładzie prostego endpointu REST API:

@GetMapping("/users/{id}")
public UserDto getUser(@PathVariable Long id) {
    return userService.findById(id);
}
  1. Klient wysyła żądanie HTTP GET /users/1, które trafia do kontenera servletów (np. Tomcat), a następnie do DispatcherServlet.
  2. DispatcherServlet wykorzystuje HandlerMapping do znalezienia metody kontrolera odpowiadającej przesłanemu żądaniu. W tym przypadku jest to metoda getUser().
  3. DispatcherServlet wybiera odpowiedni HandlerAdapter, który przygotowuje argumenty metody (np. konwertuje identyfikator użytkownika na typ Long) i wywołuje kontroler.
  4. Kontroler komunikuje się z warstwą biznesową aplikacji i zwraca obiekt UserDto.
  5. W przypadku kontrolera REST mechanizm obsługi zwracanej wartości wykorzystuje odpowiedni HttpMessageConverter, który serializuje obiekt UserDto do formatu JSON.
  6. Odpowiedź HTTP zostaje zwrócona klientowi.

W przypadku tradycyjnej aplikacji webowej ostatnie etapy wyglądają nieco inaczej. Kontroler zwraca nazwę widoku, a DispatcherServlet wykorzystuje ViewResolver do odnalezienia odpowiedniego widoku, który następnie generuje stronę HTML na podstawie danych modelu.

HandlerMapping a HandlerAdapter

Warto zwrócić uwagę na różnicę pomiędzy tymi dwoma komponentami:

  • HandlerMapping odpowiada na pytanie: którą metodę należy wywołać?
  • HandlerAdapter odpowiada na pytanie: w jaki sposób należy ją wywołać i obsłużyć jej wynik?

Konfiguracja Spring MVC w Spring Boot 4

W Spring Boot 4 do obsługi Spring MVC wykorzystujemy starter spring-boot-starter-webmvc.

W przypadku Mavena:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>

Uwaga: W poprzednich wersjach Spring Boot wykorzystywano spring-boot-starter-web. W Spring Boot 4 starter ten został oznaczony jako deprecated, a jego zalecanym zamiennikiem jest spring-boot-starter-webmvc

Automatyczna konfiguracja

Po dodaniu odpowiedniej zależności Spring Boot automatycznie konfiguruje środowisko niezbędne do obsługi żądań HTTP, w tym:

  • wbudowany kontener servletów (domyślnie Apache Tomcat),
  • DispatcherServlet,
  • HandlerMapping i HandlerAdapter,
  • konwertery HttpMessageConverter,
  • mechanizmy obsługi wyjątków,
  • mechanizmy obsługi widoków i zasobów statycznych.

Dzięki temu nie musisz samodzielnie konfigurować infrastruktury Spring MVC.

Własna konfiguracja – WebMvcConfigurer

Jeżeli domyślna konfiguracja Spring MVC nie jest wystarczająca, możemy ją rozszerzyć poprzez implementację interfejsu WebMvcConfigurer.

Przykładowo możemy skonfigurować mechanizm CORS (Cross-Origin Resource Sharing), umożliwiający aplikacji frontendowej działającej pod innym adresem komunikację z naszym REST API.

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("http://localhost:3000")
                .allowedMethods("GET", "POST", "PUT", "DELETE");
    }
}

Interfejs WebMvcConfigurer pozwala również na:

  • rejestrowanie własnych konwerterów i formaterów,
  • konfigurowanie mechanizmu walidacji,
  • konfigurowanie obsługi zasobów statycznych,
  • dostosowywanie konwerterów HttpMessageConverter,
  • konfigurowanie mechanizmu wersjonowania API.

Adnotacja @EnableWebMvc

Spring MVC udostępnia również adnotację @EnableWebMvc, która umożliwia przejęcie kontroli nad konfiguracją frameworka.

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
}

Należy jednak pamiętać, że zastosowanie tej adnotacji w aplikacji Spring Boot powoduje wyłączenie automatycznej konfiguracji Spring MVC dostarczanej przez Spring Boot. Nie oznacza to wyłączenia wszystkich mechanizmów Auto-configuration w aplikacji.

Kontrolery – @Controller i @RestController

Kontrolery w Spring MVC to komponenty odpowiedzialne za obsługę żądań HTTP. Ich głównym zadaniem jest odbieranie danych od klienta, komunikacja z warstwą biznesową aplikacji oraz zwracanie odpowiedzi HTTP.

Spring MVC udostępnia dwie podstawowe adnotacje umożliwiające definiowanie kontrolerów:

  • @Controller – wykorzystywana przede wszystkim w tradycyjnych aplikacjach webowych generujących widoki HTML.
  • @RestController – wykorzystywana przede wszystkim podczas tworzenia REST API.

Adnotacja @Controller

Adnotacja @Controller jest specjalizacją adnotacji @Component, dzięki czemu oznaczone nią klasy mogą być automatycznie wykrywane i rejestrowane jako beany w kontekście Springa.

W przypadku tradycyjnej aplikacji webowej metoda kontrolera może zwracać nazwę widoku, który zostanie wykorzystany do wygenerowania odpowiedzi HTTP.

@Controller
public class UserController {

    @GetMapping("/users")
    public String getUsers(Model model) {
        model.addAttribute("users", List.of("Adam", "Anna"));
        return "users";
    }
}

W powyższym przykładzie wartość "users" nie jest bezpośrednio zwracana klientowi. Spring MVC wykorzystuje ViewResolver do odnalezienia odpowiedniego widoku, np. szablonu users.html.

Adnotacja @ResponseBody

Jeżeli chcemy, aby wartość zwracana przez metodę kontrolera została zapisana bezpośrednio w treści odpowiedzi HTTP, możemy wykorzystać adnotację @ResponseBody.

@Controller
public class UserController {

    @ResponseBody
    @GetMapping("/users")
    public List<String> getUsers() {
        return List.of("Adam", "Anna");
    }
}

W tym przypadku Spring MVC nie korzysta z mechanizmu rozwiązywania widoków. Zamiast tego wykorzystuje odpowiedni HttpMessageConverter, aby przekształcić zwracaną listę do formatu JSON.

Odpowiedź HTTP będzie zawierała:

["Adam", "Anna"]

Adnotacja @RestController

Adnotacja @RestController jest połączeniem dwóch adnotacji:

  • @Controller
  • @ResponseBody

Dzięki temu nie musimy umieszczać adnotacji @ResponseBody nad każdą metodą kontrolera.

@RestController
public class UserController {

    @GetMapping("/users")
    public List<String> getUsers() {
        return List.of("Adam", "Anna");
    }
}

Powyższy przykład działa tak samo jak poprzedni, w którym wykorzystaliśmy @Controller wraz z @ResponseBody.

@Controller a @RestController – porównanie

Cecha@Controller@RestController
Główne zastosowanieTradycyjne aplikacje weboweREST API
Obsługa widoków HTMLTakDomyślnie nie
Zwracanie danych JSONTak, np. z @ResponseBodyTak, bez dodatkowej adnotacji
Domyślna interpretacja zwracanej wartości typu StringNazwa widokuTreść odpowiedzi HTTP
Rejestracja jako bean SpringaTakTak

Mapowanie żądań HTTP – @RequestMapping, @GetMapping, @PostMapping

Spring MVC umożliwia mapowanie przychodzących żądań HTTP na odpowiednie metody kontrolerów za pomocą adnotacji. Na podstawie adresu URL, metody HTTP oraz dodatkowych parametrów żądania framework określa, która metoda kontrolera powinna zostać wywołana.

Adnotacja @RequestMapping

Podstawową adnotacją służącą do mapowania żądań HTTP jest @RequestMapping. Może być stosowana zarówno na poziomie klasy, jak i poszczególnych metod kontrolera.

@RestController
@RequestMapping("/users")
public class UserController {

    @RequestMapping(method = RequestMethod.GET)
    public List<UserDto> getUsers() {
        return userService.findAll();
    }

    @RequestMapping(path = "/{id}", method = RequestMethod.GET)
    public UserDto getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

Adnotacja umieszczona na poziomie klasy definiuje wspólny fragment ścieżki dla wszystkich metod kontrolera.

W powyższym przykładzie dostępne są dwa endpointy:

  • GET /users
  • GET /users/{id}

Jeżeli nie określimy parametru method, adnotacja @RequestMapping domyślnie dopasowuje wszystkie metody HTTP.

Adnotacje dedykowane metodom HTTP

Spring MVC udostępnia również uproszczone odpowiedniki adnotacji @RequestMapping, dedykowane poszczególnym metodom HTTP.

AdnotacjaMetoda HTTPTypowe zastosowanie
@GetMappingGETPobieranie danych
@PostMappingPOSTTworzenie zasobów
@PutMappingPUTZastępowanie zasobów
@PatchMappingPATCHCzęściowa aktualizacja zasobów
@DeleteMappingDELETEUsuwanie zasobów

Przykładowo poniższe dwie adnotacje są równoważne:

@RequestMapping(path = "/users", method = RequestMethod.GET)
@GetMapping("/users")

W praktyce zaleca się korzystanie z dedykowanych adnotacji, ponieważ zwiększają czytelność kodu.

Przykładowy kontroler REST

@RestController
@RequestMapping("/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping
    public List<UserDto> getUsers() {
        return userService.findAll();
    }

    @GetMapping("/{id}")
    public UserDto getUser(@PathVariable Long id) {
        return userService.findById(id);
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public UserDto createUser(@RequestBody UserDto user) {
        return userService.create(user);
    }

    @PutMapping("/{id}")
    public UserDto updateUser(@PathVariable Long id,
                              @RequestBody UserDto user) {
        return userService.update(id, user);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(@PathVariable Long id) {
        userService.delete(id);
    }
}

Powyższy kontroler udostępnia podstawowe operacje CRUD (Create, Read, Update, Delete) na zasobie reprezentującym użytkowników.

Dodatkowe parametry mapowania żądań

Mapowanie żądań w Spring MVC nie musi ograniczać się wyłącznie do adresu URL oraz metody HTTP. Możemy również uwzględnić dodatkowe warunki.

ParametrZnaczenie
path / valueŚcieżka endpointu.
methodObsługiwana metoda HTTP.
consumesAkceptowany format danych wejściowych (Content-Type).
producesFormat zwracanych danych, dopasowywany do nagłówka Accept.
paramsWarunki dotyczące parametrów żądania.
headersWarunki dotyczące nagłówków HTTP.
versionWersja API (od Spring Framework 7).

Przykładowo możemy określić, że endpoint przyjmuje oraz zwraca dane wyłącznie w formacie JSON:

@PostMapping(
    consumes = MediaType.APPLICATION_JSON_VALUE,
    produces = MediaType.APPLICATION_JSON_VALUE
)
public UserDto createUser(@RequestBody UserDto user) {
    return userService.create(user);
}

Możemy również zdefiniować dwie metody obsługujące ten sam adres URL i tę samą metodę HTTP, ale różniące się wymaganymi parametrami:

@GetMapping(params = "active=true")
public List<UserDto> getActiveUsers() {
    return userService.findActive();
}

@GetMapping(params = "active=false")
public List<UserDto> getInactiveUsers() {
    return userService.findInactive();
}

W zależności od wartości parametru active Spring MVC wybierze odpowiednią metodę kontrolera:

GET /users?active=true
GET /users?active=false

Przekazywanie danych do kontrolera

Spring MVC umożliwia automatyczne pobieranie danych z przychodzących żądań HTTP i przekazywanie ich jako argumentów metod kontrolera. Dzięki temu programista nie musi samodzielnie odczytywać i przetwarzać danych z obiektu HttpServletRequest.

Do najważniejszych adnotacji wykorzystywanych w tym celu należą:

AdnotacjaŹródło danych
@PathVariableFragment ścieżki URL
@RequestParamParametry żądania, np. query parameters
@RequestBodyTreść żądania HTTP
@RequestHeaderNagłówki HTTP
@CookieValueCiasteczka HTTP
@ModelAttributeDane formularza i inne parametry żądania

Adnotacja @PathVariable

Adnotacja @PathVariable umożliwia pobranie wartości stanowiącej część ścieżki URL. Najczęściej wykorzystywana jest do przekazywania identyfikatorów zasobów.

@GetMapping("/users/{id}")
public UserDto getUser(@PathVariable Long id) {
    return userService.findById(id);
}

Przykładowe żądanie:

GET /users/15

Spring MVC automatycznie pobierze wartość 15 ze ścieżki URL, przekonwertuje ją na typ Long i przekaże jako argument metody.

Jeżeli nazwa argumentu różni się od nazwy zmiennej w ścieżce, możemy wskazać ją jawnie:

@GetMapping("/users/{id}")
public UserDto getUser(@PathVariable("id") Long userId) {
    return userService.findById(userId);
}

Adnotacja @RequestParam

Adnotacja @RequestParam umożliwia pobieranie parametrów żądania HTTP. Najczęściej wykorzystywana jest do filtrowania, sortowania oraz stronicowania wyników.

@GetMapping("/users")
public List<UserDto> getUsers(@RequestParam boolean active) {
    return userService.findByActive(active);
}

Przykładowe żądanie:

GET /users?active=true

Domyślnie parametr oznaczony adnotacją @RequestParam jest wymagany. Możemy jednak zmienić to zachowanie za pomocą właściwości required lub określić wartość domyślną za pomocą defaultValue.

@GetMapping("/users")
public List<UserDto> getUsers(
        @RequestParam(required = false) String name,
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size) {

    return userService.findUsers(name, page, size);
}

Przykładowe żądanie:

GET /users?name=Adam&page=2&size=10

Jeżeli klient nie przekaże parametrów page oraz size, Spring MVC wykorzysta zdefiniowane wartości domyślne.

Adnotacja @RequestBody

Adnotacja @RequestBody umożliwia odczytanie treści żądania HTTP i przekonwertowanie jej na obiekt Java.

Najczęściej wykorzystywana jest w przypadku metod POST, PUT oraz PATCH.

public record CreateUserRequest(
        String name,
        String email
) {}
@PostMapping("/users")
public UserDto createUser(@RequestBody CreateUserRequest request) {
    return userService.create(request);
}

Przykładowe żądanie:

POST /users
Content-Type: application/json

{
    "name": "Adam",
    "email": "adam@example.com"
}

Spring MVC wykorzysta odpowiedni HttpMessageConverter, który przy użyciu biblioteki Jackson dokona deserializacji danych JSON do obiektu CreateUserRequest.

Adnotacja @RequestHeader

Adnotacja @RequestHeader umożliwia odczytywanie wartości nagłówków HTTP.

@GetMapping("/users")
public List<UserDto> getUsers(
        @RequestHeader("Accept-Language") String language) {

    return userService.findAll(language);
}

Przykładowe żądanie:

GET /users
Accept-Language: pl

Adnotacja ta może być wykorzystywana m.in. do odczytywania preferowanego języka, identyfikatorów żądań czy niestandardowych nagłówków HTTP.

Podobnie jak w przypadku @RequestParam, możemy korzystać z właściwości required oraz defaultValue.

Adnotacja @CookieValue

Adnotacja @CookieValue umożliwia pobranie wartości ciasteczka przesłanego przez klienta.

@GetMapping("/preferences")
public String getPreferences(
        @CookieValue(name = "theme", defaultValue = "light")
        String theme) {

    return theme;
}

Przykładowe żądanie:

GET /preferences
Cookie: theme=dark

Adnotacja ta może być wykorzystywana np. do odczytywania preferencji użytkownika.

Adnotacja @ModelAttribute

Adnotacja @ModelAttribute pozwala na powiązanie parametrów żądania z obiektem Java. Mechanizm ten nazywany jest Data Binding.

public record UserSearchCriteria(
        String name,
        Boolean active
) {}
@GetMapping("/users")
public List<UserDto> getUsers(
        @ModelAttribute UserSearchCriteria criteria) {

    return userService.findUsers(criteria);
}

Przykładowe żądanie:

GET /users?name=Adam&active=true

Spring MVC utworzy obiekt UserSearchCriteria i przypisze do niego wartości odpowiadających mu parametrów żądania.

Adnotacja @ModelAttribute jest często wykorzystywana podczas obsługi formularzy HTML, ale sprawdza się również w REST API, np. podczas grupowania parametrów wyszukiwania.

@RequestParam a @PathVariable a @RequestBody

Cecha@RequestParam@PathVariable@RequestBody
Źródło danychParametry żądaniaŚcieżka URLTreść żądania
Przykład/users?active=true/users/15{"name":"Adam"}
Typowe zastosowanieFiltrowanie i stronicowanieIdentyfikacja zasobuTworzenie i aktualizacja zasobu
Mechanizm konwersjiConversionServiceConversionServiceHttpMessageConverter

Zwracanie odpowiedzi HTTP – ResponseEntity

Spring MVC umożliwia automatyczne przekształcanie wartości zwracanych przez metody kontrolera na odpowiedzi HTTP. W przypadku REST API odpowiedzi te najczęściej zawierają dane w formacie JSON.

Programista może zwrócić bezpośrednio obiekt Java lub wykorzystać klasę ResponseEntity, która zapewnia większą kontrolę nad generowaną odpowiedzią.

Zwracanie obiektów Java

Najprostszym sposobem zwracania danych w REST API jest zwrócenie obiektu Java bezpośrednio z metody kontrolera oznaczonego adnotacją @RestController.

public record UserDto(Long id, String name) {}
@GetMapping("/users/{id}")
public UserDto getUser(@PathVariable Long id) {
    return new UserDto(id, "Adam");
}

Przykładowa odpowiedź HTTP:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "Adam"
}

Spring MVC automatycznie serializuje obiekt do formatu JSON za pomocą odpowiedniego konwertera i domyślnie zwraca kod odpowiedzi HTTP 200 OK.

Adnotacja @ResponseStatus

Jeżeli chcemy zmienić domyślny kod odpowiedzi HTTP, możemy wykorzystać adnotację @ResponseStatus.

@PostMapping("/users")
@ResponseStatus(HttpStatus.CREATED)
public UserDto createUser(@RequestBody CreateUserRequest request) {
    return userService.create(request);
}

W tym przypadku poprawne wykonanie metody spowoduje zwrócenie odpowiedzi z kodem 201 Created.

Ograniczeniem tego rozwiązania jest fakt, że kod odpowiedzi jest określony statycznie na poziomie adnotacji.

ResponseEntity

ResponseEntity to klasa reprezentująca pełną odpowiedź HTTP. Umożliwia określenie trzech elementów odpowiedzi:

  • kodu statusu HTTP,
  • nagłówków HTTP,
  • treści odpowiedzi (body).

W przeciwieństwie do adnotacji @ResponseStatus pozwala na dynamiczne określanie kodu odpowiedzi w zależności od wyniku wykonania metody.

@GetMapping("/users/{id}")
public ResponseEntity<UserDto> getUser(@PathVariable Long id) {
    return userService.findById(id)
            .map(ResponseEntity::ok)
            .orElseGet(() -> ResponseEntity.notFound().build());
}

Zakładając, że metoda findById() zwraca Optional<UserDto>, w zależności od tego, czy użytkownik istnieje, kontroler zwróci:

  • 200 OK wraz z danymi użytkownika,
  • 404 Not Found bez treści odpowiedzi.

Najważniejsze metody ResponseEntity

MetodaKod HTTP
ResponseEntity.ok(body)200 OK
ResponseEntity.created(uri)201 Created
ResponseEntity.noContent()204 No Content
ResponseEntity.badRequest()400 Bad Request
ResponseEntity.notFound()404 Not Found
ResponseEntity.internalServerError()500 Internal Server Error
ResponseEntity.status(status)Dowolny wskazany status

Dodawanie nagłówków HTTP

Klasa ResponseEntity umożliwia również ustawianie nagłówków odpowiedzi HTTP.

@PostMapping("/users")
public ResponseEntity<UserDto> createUser(
        @RequestBody CreateUserRequest request) {

    UserDto user = userService.create(request);
    URI location = URI.create("/users/" + user.id());

    return ResponseEntity.created(location)
            .body(user);
}

Przykładowa odpowiedź:

HTTP/1.1 201 Created
Location: /users/1
Content-Type: application/json

{
    "id": 1,
    "name": "Adam"
}

Metoda created() ustawia zarówno kod odpowiedzi 201 Created, jak i nagłówek Location, wskazujący adres nowo utworzonego zasobu.

Możemy również dodawać własne nagłówki za pomocą metody header():

return ResponseEntity.ok()
        .header("X-Custom-Header", "example")
        .body(user);

Walidacja danych wejściowych – @Valid i @Validated

Walidacja danych wejściowych pozwala zweryfikować poprawność danych przesyłanych przez klienta, zanim zostaną one przekazane do logiki biznesowej aplikacji.

Spring MVC integruje się ze standardem Jakarta Bean Validation, którego popularną implementacją jest Hibernate Validator. Mechanizm ten umożliwia deklaratywne definiowanie reguł walidacji za pomocą adnotacji.

Konfiguracja walidacji

W Spring Boot 4 wystarczy dodać odpowiednią zależność:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

Najważniejsze adnotacje walidacyjne

AdnotacjaZnaczenie
@NotNullWartość nie może być null.
@NotEmptyWartość nie może być null ani pusta.
@NotBlankTekst nie może być pusty ani zawierać wyłącznie białych znaków.
@SizeOkreśla dopuszczalny rozmiar tekstu lub kolekcji.
@Min / @MaxOkreśla minimalną i maksymalną wartość liczbową.
@PositiveWartość musi być większa od zera.
@EmailWeryfikuje format adresu e-mail.

Adnotacja @Valid

Adnotacja @Valid, pochodząca z pakietu jakarta.validation, umożliwia uruchomienie walidacji obiektu przekazanego do metody kontrolera.

Zdefiniujmy przykładowy obiekt reprezentujący dane nowego użytkownika:

public record CreateUserRequest(

        @NotBlank
        @Size(min = 2, max = 50)
        String name,

        @NotBlank
        @Email
        String email,

        @NotNull
        @Min(18)
        Integer age
) {}

Następnie wykorzystajmy go w kontrolerze:

@PostMapping("/users")
@ResponseStatus(HttpStatus.CREATED)
public UserDto createUser(
        @Valid @RequestBody CreateUserRequest request) {

    return userService.create(request);
}

Po otrzymaniu żądania Spring MVC:

  1. Przekształci dane JSON na obiekt CreateUserRequest.
  2. Zweryfikuje poprawność danych zgodnie z zadeklarowanymi regułami.
  3. Wywoła metodę kontrolera, jeżeli walidacja zakończy się powodzeniem.

W przypadku niepoprawnych danych Spring MVC zgłosi wyjątek MethodArgumentNotValidException, który domyślnie skutkuje zwróceniem odpowiedzi HTTP 400 Bad Request.

Własne komunikaty walidacyjne

Adnotacje walidacyjne umożliwiają definiowanie własnych komunikatów błędów za pomocą parametru message.

@NotBlank(message = "Name is required")
@Size(min = 2, max = 50, message = "Invalid name length")
String name;

@Email(message = "Invalid email address")
String email;

Komunikaty te można następnie wykorzystać podczas przygotowywania odpowiedzi HTTP zawierającej szczegółowe informacje o błędach walidacji.

Walidacja parametrów metod kontrolera

Spring MVC umożliwia również walidację pojedynczych argumentów metod, np. parametrów oznaczonych adnotacjami @RequestParam lub @PathVariable.

@GetMapping("/users")
public List<UserDto> getUsers(
        @RequestParam(defaultValue = "0") @Min(0) int page,
        @RequestParam(defaultValue = "20") @Min(1) @Max(100) int size) {

    return userService.findAll(page, size);
}

Przesłanie żądania:

GET /users?page=-1&size=200

spowoduje zgłoszenie wyjątku HandlerMethodValidationException i zwrócenie odpowiedzi 400 Bad Request.

Adnotacja @Validated

Od Spring Framework 6.1 (Spring Boot 3.2) Spring MVC posiada wbudowany mechanizm walidacji parametrów metod kontrolera. W związku z tym stosowanie adnotacji @Validated na poziomie klasy kontrolera nie jest już konieczne.

Adnotacja ta pozostaje jednak przydatna podczas walidacji metod innych komponentów Springa, np. w warstwie serwisowej.

@Service
@Validated
public class UserService {

    public UserDto findById(@Positive Long id) {
        // ...
    }
}

W powyższym przykładzie walidacja argumentów metody odbywa się za pośrednictwem mechanizmu Spring AOP (proxy).

Warto pamiętać, że @Validated nadal może być wykorzystywana w kontrolerach do wskazywania grup walidacyjnych (Validation Groups). W przypadku standardowej walidacji danych wejściowych nie ma jednak potrzeby jej stosowania.

Obsługa wyjątków – @ExceptionHandler, @ControllerAdvice

Podczas przetwarzania żądań HTTP mogą wystąpić różnego rodzaju błędy, np. niepoprawne dane wejściowe, brak poszukiwanego zasobu czy problemy z komunikacją z bazą danych.

Spring MVC udostępnia mechanizmy pozwalające na centralizację obsługi wyjątków oraz przekształcanie ich w odpowiednie odpowiedzi HTTP. Dzięki temu nie musimy umieszczać bloków try-catch w każdej metodzie kontrolera.

Adnotacja @ExceptionHandler

Adnotacja @ExceptionHandler pozwala wskazać metodę odpowiedzialną za obsługę określonego typu wyjątku.

Załóżmy, że posiadamy własny wyjątek informujący o braku użytkownika w systemie.

public class UserNotFoundException extends RuntimeException {

    public UserNotFoundException(Long id) {
        super("User with id " + id + " not found");
    }
}

Możemy obsłużyć go bezpośrednio w kontrolerze:

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public UserDto getUser(@PathVariable Long id) {
        return userService.findById(id);
    }

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFound(
            UserNotFoundException ex) {

        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(ex.getMessage());
    }
}

Jeżeli podczas wykonywania metody getUser() zostanie zgłoszony wyjątek UserNotFoundException, Spring MVC automatycznie wywoła metodę handleUserNotFound(), która zwróci odpowiedź HTTP 404 Not Found.

Ograniczeniem tego rozwiązania jest fakt, że metoda obsługi wyjątków zdefiniowana w kontrolerze dotyczy wyłącznie tego kontrolera.

@ControllerAdvice i @RestControllerAdvice

Adnotacja @ControllerAdvice umożliwia definiowanie globalnych mechanizmów obsługi wyjątków współdzielonych przez wiele kontrolerów.

W przypadku REST API najczęściej wykorzystuje się adnotację @RestControllerAdvice, która stanowi połączenie:

  • @ControllerAdvice,
  • @ResponseBody.

Przenieśmy zatem obsługę wyjątku do osobnej klasy:

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFound(
            UserNotFoundException ex) {

        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(ex.getMessage());
    }
}

Od tego momentu wyjątek UserNotFoundException może zostać obsłużony niezależnie od tego, w którym kontrolerze został zgłoszony lub z którego serwisu został propagowany do warstwy webowej.

Takie rozwiązanie pozwala oddzielić logikę obsługi błędów od właściwej logiki kontrolerów.

Wersjonowanie API w Spring MVC

Wersjonowanie API (API Versioning) to mechanizm umożliwiający rozwijanie interfejsu API przy jednoczesnym zachowaniu kompatybilności z istniejącymi klientami. Dzięki niemu aplikacja może udostępniać kilka wersji tego samego endpointu, różniących się np. strukturą zwracanych danych.

Wersjonowanie API od Spring Framework 7

Spring Framework 7 wprowadził natywne wsparcie dla wersjonowania API poprzez dodanie parametru version do adnotacji @RequestMapping oraz jej pochodnych, takich jak @GetMapping czy @PostMapping.

W Spring Boot 4 możemy skonfigurować mechanizm wersjonowania za pomocą pliku application.yml:

spring:
  mvc:
    apiversion:
      default: "1.0"
      use:
        header: API-Version

Powyższa konfiguracja wskazuje, że wersja API będzie odczytywana z nagłówka API-Version. Jeżeli klient nie przekaże tego nagłówka, wykorzystana zostanie wersja domyślna 1.0.

Następnie możemy zdefiniować kontroler:

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping(version = "1.0")
    public List<UserDtoV1> getUsersV1() {
        return userService.findAllV1();
    }

    @GetMapping(version = "2.0")
    public List<UserDtoV2> getUsersV2() {
        return userService.findAllV2();
    }
}

Przykładowe żądanie:

GET /api/users
API-Version: 2.0

Spring MVC automatycznie wybierze metodę getUsersV2(). Jeżeli klient przekaże nieobsługiwaną wersję API, framework zwróci odpowiedź 400 Bad Request. Home+1

Wersje dokładne i bazowe

Spring Framework 7 umożliwia definiowanie dwóch rodzajów mapowania wersji:

MapowanieZnaczenie
version = "1.0"Obsługuje wyłącznie wersję 1.0.
version = "1.0+"Obsługuje wersję 1.0 oraz wyższe obsługiwane wersje, o ile nie istnieje bardziej szczegółowe mapowanie.
@GetMapping(version = "1.0+")
public List<UserDtoV1> getUsersV1() {
    return userService.findAllV1();
}

@GetMapping(version = "2.0+")
public List<UserDtoV2> getUsersV2() {
    return userService.findAllV2();
}

Mechanizm wersji bazowych (Baseline Versions) pozwala uniknąć konieczności definiowania nowych metod kontrolera dla endpointów, które nie zmieniły się pomiędzy kolejnymi wersjami API.

Spring MVC a Spring WebFlux

Spring Framework udostępnia dwa moduły przeznaczone do tworzenia aplikacji webowych: Spring MVC oraz Spring WebFlux. Oba umożliwiają tworzenie REST API, jednak różnią się przede wszystkim modelem przetwarzania żądań HTTP.

Spring MVC

Spring MVC opiera się na Servlet API i tradycyjnym, blokującym modelu przetwarzania żądań. W typowym przypadku każde żądanie HTTP jest obsługiwane przez osobny wątek, pobierany z puli wątków kontenera servletów.

Jeżeli podczas obsługi żądania wykonywana jest blokująca operacja, np. zapytanie do bazy danych za pomocą JDBC, wątek oczekuje na jej zakończenie.

@GetMapping("/users/{id}")
public UserDto getUser(@PathVariable Long id) {
    return userService.findById(id);
}

Spring WebFlux

Spring WebFlux został wprowadzony w Spring Framework 5 i wykorzystuje reaktywny, nieblokujący model przetwarzania danych oparty na bibliotece Project Reactor.

Zamiast blokować wątek podczas oczekiwania na zakończenie operacji wejścia-wyjścia, framework może wykorzystać go do obsługi innych zadań.

Spring WebFlux wykorzystuje dwa podstawowe typy reaktywne:

  • Mono<T> – reprezentuje zero lub jeden element.
  • Flux<T> – reprezentuje strumień zawierający zero lub więcej elementów.

Przykładowy kontroler reaktywny:

@GetMapping("/users/{id}")
public Mono<UserDto> getUser(@PathVariable Long id) {
    return userService.findById(id);
}

Aby w pełni wykorzystać możliwości Spring WebFlux, również pozostałe warstwy aplikacji powinny korzystać z nieblokujących mechanizmów, np. R2DBC zamiast JDBC.

Spring MVC a Spring WebFlux – porównanie

CechaSpring MVCSpring WebFlux
Model programowaniaImperatywnyReaktywny
Przetwarzanie żądańDomyślnie blokująceNieblokujące
Zarządzanie wątkamiTradycyjnie wątek na żądanieEvent Loop
Domyślny serwer w Spring BootTomcatReactor Netty
Główny komponentDispatcherServletDispatcherHandler
Dostęp do bazy danychJDBC, JPA, HibernateR2DBC, Reactive MongoDB
Typy zwracanych danychObiekty JavaMono, Flux
Stopień skomplikowaniaNiższyWyższy
BackpressureBrak natywnego mechanizmu Reactive StreamsTak

Kiedy wybrać Spring MVC, a kiedy Spring WebFlux?

Spring MVC sprawdzi się w większości klasycznych aplikacji biznesowych, szczególnie tych wykorzystujących relacyjne bazy danych oraz technologie takie jak Hibernate, JPA czy JDBC.

Spring WebFlux warto rozważyć w systemach obsługujących dużą liczbę równoczesnych połączeń, wykonujących wiele operacji sieciowych lub przetwarzających strumienie danych.

Dobre praktyki

Podczas tworzenia aplikacji webowych z wykorzystaniem Spring MVC warto przestrzegać kilku zasad, które ułatwiają utrzymanie kodu oraz zwiększają bezpieczeństwo aplikacji.

1. Oddzielaj logikę biznesową od kontrolerów

Kontroler powinien odpowiadać za komunikację HTTP, natomiast logika biznesowa powinna znajdować się w warstwie serwisowej.

@PostMapping("/users")
@ResponseStatus(HttpStatus.CREATED)
public UserDto createUser(
        @Valid @RequestBody CreateUserRequest request) {

    return userService.create(request);
}

Takie podejście określane jest jako Thin Controller (cienki kontroler).

2. Korzystaj z DTO zamiast encji

Nie należy bezpośrednio zwracać encji JPA z kontrolerów. Wykorzystanie DTO pozwala oddzielić strukturę API od modelu bazodanowego, ograniczyć ilość zwracanych danych oraz uniknąć problemów związanych z mechanizmem Lazy Loading.

Dobrą praktyką jest również stosowanie oddzielnych obiektów reprezentujących dane wejściowe i wyjściowe, np. CreateUserRequest oraz UserDto.

3. Stosuj deklaratywną walidację danych

Zamiast ręcznie sprawdzać poprawność danych wejściowych w kontrolerze, wykorzystuj Jakarta Bean Validation oraz adnotacje takie jak @Valid, @NotNull czy @NotBlank.

W przypadku bardziej złożonych reguł warto rozważyć implementację własnych walidatorów. Walidacja reguł biznesowych powinna natomiast pozostać w warstwie biznesowej.

4. Centralizuj obsługę wyjątków

Zamiast powielać bloki try-catch w poszczególnych kontrolerach, wykorzystuj @RestControllerAdvice oraz @ExceptionHandler.

Pozwala to zachować spójny format odpowiedzi błędów w całej aplikacji oraz oddzielić obsługę wyjątków od pozostałej logiki.

5. Stosuj odpowiednie kody odpowiedzi HTTP

Kod odpowiedzi HTTP powinien odzwierciedlać rzeczywisty rezultat wykonanej operacji.

6. Twórz bezstanowe kontrolery

Kontrolery domyślnie są beanami o zakresie singleton, dlatego nie powinny przechowywać w polach instancji danych związanych z konkretnym żądaniem HTTP. Mogłoby to prowadzić do problemów podczas równoczesnej obsługi wielu żądań.

7. Dbaj o kompatybilność wsteczną API

Wprowadzając zmiany w istniejącym API, należy uwzględnić klientów korzystających z jego dotychczasowej wersji. W przypadku zmian niekompatybilnych wstecz warto udostępnić nową wersję API, wykorzystując np. mechanizm wersjonowania wprowadzony w Spring Framework 7.

Podsumowanie

Spring MVC jest jednym z najważniejszych modułów Spring Framework, umożliwiającym tworzenie zarówno tradycyjnych aplikacji webowych, jak i REST API. Jego architektura oparta na wzorcu Front Controller oraz centralnym komponencie DispatcherServlet pozwala na oddzielenie logiki biznesowej od mechanizmów obsługi żądań HTTP.

Dzięki deklaratywnemu podejściu do mapowania żądań, walidacji danych oraz obsługi wyjątków Spring MVC znacząco upraszcza implementację warstwy webowej aplikacji. Integracja ze Spring Boot dodatkowo ogranicza ilość wymaganej konfiguracji.

Źródła:

Spring Framework 7 – Spring Web MVC

Spring Boot 4 – Servlet Web Applications

Spring Framework – Validation

Spring Framework – API Versioning

Dodaj komentarz