Создание REST-контроллеров в Spring (@RestController, @GetMapping и др.)

Создание REST-контроллеров в Spring (@RestController, @GetMapping и др.)

Spring MVC Controller: класс, помеченный аннотацией @RestController (или @Controller + @ResponseBody) для обработки веб-запросов.
Маршрутизация запросов: используем аннотации @RequestMapping/@GetMapping/@PostMapping и др. для привязки URL-путей и HTTP-методов к методам контроллера.
Автосериализация ответа: @RestController автоматически сериализует возвращаемые объекты в JSON (благодаря встроенному Jackson) и пишет прямо в тело ответа (без представления).
Пример:
@RestController  
@RequestMapping("/api/hello")  
class HelloController {  
@GetMapping  
public String sayHello() {  
return "Hello, world!";  
}  
}
(В примере выше GET-запрос на /api/hello вернет строку “Hello, world!” в теле ответа.)

Пояснение:

В Spring MVC веб-контроллеры реализуют паттерн “Controller” из MVC – принимают HTTP-запросы и возвращают результат. Для создания RESTful веб-сервиса используется специализированная аннотация @RestController. Этот класс-аннотация сочетает функциональность обычного @Controller и @ResponseBody. Что это означает?
Аннотация @Controller исторически применяется для MVC-контроллеров, которые возвращают представления (например, HTML-страницы через Thymeleaf). Если метод в обычном @Controller возвращает строку, Spring трактует ее как имя шаблона для отображения. Чтобы метод контроллера вернул данные (например, JSON) вместо имени представления, в старых версиях требовалось на каждый метод добавлять @ResponseBody.
Аннотация @RestController упрощает жизнь разработчику REST API. Помечая класс как @RestController, мы тем самым говорим, что все методы в нем по умолчанию возвращают не представление, а именно данные, и результат каждого метода автоматически сериализуется (преобразуется) в JSON и помещается в тело HTTP-ответа. Другими словами, @RestController подразумевает неявный @ResponseBody для всех методов, поэтому можно просто возвращать объекты Java из методов, не заботясь о ручной конвертации или шаблонах.
При запуске Spring-приложения с зависимостью spring-boot-starter-web, под капотом поднимается встроенный сервер (например, Tomcat) и настраивается Spring MVC. Все классы с аннотациями контроллеров регистрируются как обработчики маршрутов.
Маршрутизация (Mapping): Для привязки методов контроллера к конкретным URL и HTTP-методам используются аннотации. Базовая аннотация – @RequestMapping, которая может указываться на уровне класса и/или метода. Она позволяет задать путь (value или path) и опционально ограничить метод запроса (method = RequestMethod.GET/POST и т.д.), а также другие условия (такие как заголовки или производимый/потребляемый контент). В современном Spring чаще применяют специализированные аннотации сокращения: @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping. Они задают и тип HTTP-метода, и путь, и делают код декларативнее. Эти аннотации используются только на уровне методов. Например:
@RestController
@RequestMapping("/api/users")         // базовый префикс пути для всех методов этого контроллера
public class UserController {
@GetMapping("/{id}")             // обрабатывает GET /api/users/{id}
public User getUser(@PathVariable Long id) {
//... получение пользователя по id
return user;
}
@PostMapping                     // обрабатывает POST /api/users
public ResponseEntity<User> addUser(@RequestBody User newUser) {
User created = userService.save(newUser);
// вернуть 201 Created с телом нового пользователя:
return ResponseEntity.status(HttpStatus.CREATED).body(created);
}
}
В примере выше класс UserController помечен @RestController и базовым путем /api/users. Метод getUser сопоставлен с GET-запросом на путь /api/users/{id}, а метод addUser – с POST-запросом на /api/users. Обратите внимание на использование @PathVariable и @RequestBody (о них подробнее в следующем разделе) и на то, что метод addUser возвращает ResponseEntity<User> с кодом 201.
Spring MVC внутренно регистрирует каждый такой метод в DispatcherServlet (фронт-контроллер). Когда приходит входящий HTTP-запрос, DispatcherServlet на основе пути и метода находит соответствующий метод контроллера (handler). Передавая запрос в метод, Spring автоматически связывает части URL, параметры, тело и пр. с аргументами метода (через аннотации, такие как @PathVariable, @RequestParam, etc). После выполнения метода, возвращенное значение (например, объект User или ResponseEntity) конвертируется в HTTP-ответ.
Преимущество использования Spring для REST в том, что большинство стандартных задач берет на себя фреймворк. Например, если метод возвращает объект или коллекцию, Spring (при наличии библиотеки Jackson) сам преобразует их в JSON. Если метод бросает исключение, Spring может сконвертировать его в понятный код ответа по умолчанию. Разработчику остается сконцентрироваться на бизнес-логике, а не на деталях протокола.
Подытожим: чтобы создать REST API на Spring MVC, достаточно написать класс-контроллер с @RestController, определить в нем методы с @GetMapping, @PostMapping и т.д., возвращающие данные. Spring Boot по convention-over-configuration сделает остальное: поднимет веб-сервер, настроит маршрутизацию, подключит JSON-конвертер. В 2025 году это по-прежнему актуальный подход, а Spring продолжает развиваться, предлагая новые утилиты (например, для документации API через OpenAPI/Swagger, или упрощенную обработку ошибок). Но фундамент остается: аннотации контроллеров и RESTful дизайн.