Создание REST-контроллеров с аннотацией @RestController

Добро пожаловать на лекцию, где мы начнем погружаться в создание REST API с помощью Spring! Сегодня мы сосредоточимся непосредственно на REST-контроллерах, которые являются основой для работы с REST API. Если вы мечтали сделать свое первое полноценное взаимодействие клиента и сервера, то эта лекция как раз для вас.

Что такое REST-контроллер в Spring?

REST-контроллер в Spring — это компонент, который позволяет обрабатывать HTTP-запросы (GET, POST, PUT, DELETE и т.д.) и возвращать данные клиенту в нужном формате (обычно JSON). Контроллер — это "связное звено" между клиентом и серверными компонентами вашего приложения, такими как сервисы и репозитории.

Ключевым моментом является использование аннотации @RestController. Она автоматически сообщает Spring, что этот класс будет обрабатывать HTTP-запросы и возвращать данные в формате JSON или другого типа (XML, текст и т.д.).

Отличие между @Controller и @RestController

Для лучшего понимания, давайте разберем разницу между этими аннотациями:

Если вам нужно взаимодействовать с клиентом через JSON, например, для мобильных приложений или SPA (Single Page Applications), то @RestController — это ваш лучший выбор. Он убирает лишнюю работу с представлениями, позволяя сосредоточиться на данных.

Настройка базового REST-контроллера

Шаг 1: Создание нового класса контроллера

Итак, давайте создадим базовый REST-контроллер для обработки запросов. Представим, что у нас есть сущность Customer, и мы хотим управлять данными об этой сущности.

package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/customers")
public class CustomerController {

    @GetMapping
    public String getAllCustomers() {
        return "Здесь будет список клиентов!";
    }

}

1. @RestController: Маркируем класс как REST-контроллер.
2. @RequestMapping("/api/customers"): Определяем базовый путь (URI) для всех запросов, связанных с клиентами.
3. @GetMapping: Указываем, что метод обрабатывает HTTP-запросы типа GET.
4. Возврат строки: Это временный пример, позже мы заменим строку на реальные объекты.

Теперь, если вы запустите приложение и откроете браузер по адресу http://localhost:8080/api/customers, вы увидите: Здесь будет список клиентов!.

Шаг 2: Возвращение данных в формате JSON

REST API обычно возвращает данные в формате JSON. В мире Spring за это отвечает библиотека Jackson, которая автоматически конвертирует Java-объекты в JSON и обратно.

Давайте модифицируем наш пример, чтобы вернуть список клиентов:

package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/api/customers")
public class CustomerController {

    @GetMapping
    public List<String> getAllCustomers() {
        return List.of("Иван Иванов", "Петр Петров", "Светлана Смирнова");
    }

}

Теперь, если вы снова зайдете по адресу http://localhost:8080/api/customers, вы получите следующий JSON:

[
  "Иван Иванов",
  "Петр Петров",
  "Светлана Смирнова"
]

Что произошло?

• Мы вернули список строк с именами клиентов.
• Jackson автоматически преобразовал List<String> в JSON массив.

Конфигурация маршрутов с использованием аннотаций

Основные аннотации маршрутов

Spring предоставляет удобные аннотации для работы с различными HTTP-методами:

Пример: работа с CRUD-операциями

Давайте создадим полноценный контроллер для управления клиентами с использованием всех перечисленных HTTP-методов. Для простоты данных пока будем использовать в памяти:

package com.example.demo.controller;

import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/api/customers")
public class CustomerController {

    private final List<String> customers = new ArrayList<>(List.of("Иван Иванов", "Петр Петров"));

    @GetMapping
    public List<String> getAllCustomers() {
        return customers;
    }

    @PostMapping
    public String addCustomer(@RequestBody String customer) {
        customers.add(customer);
        return "Клиент добавлен: " + customer;
    }

    @PutMapping("/{index}")
    public String updateCustomer(@PathVariable int index, @RequestBody String customer) {
        customers.set(index, customer);
        return "Клиент обновлен: " + customer;
    }

    @DeleteMapping("/{index}")
    public String deleteCustomer(@PathVariable int index) {
        String removed = customers.remove(index);
        return "Клиент удален: " + removed;
    }
}

1. Работа с HTTP-методами: мы создали методы для всех CRUD-операций.
2. @RequestBody: используем для получения данных из тела запроса (например, POST или PUT).
3. @PathVariable: извлекаем параметры пути (например, индекс клиента в списке).

Тестирование контроллера

Добавление нового клиента:

curl -X POST -H "Content-Type: application/json" -d "Светлана Смирнова" http://localhost:8080/api/customers

Ответ:

Клиент добавлен: Светлана Смирнова

Обновление клиента:

curl -X PUT -H "Content-Type: application/json" -d "Михаил Михайлов" http://localhost:8080/api/customers/0

Ответ:

Клиент обновлен: Михаил Михайлов

Удаление клиента:

curl -X DELETE http://localhost:8080/api/customers/1

Ответ:

Клиент удален: Петр Петров

Плюсы и практическое применение

Сегодня вы научились создавать REST-контроллеры с использованием @RestController. Это фундаментальный навык для работы с REST API. Вы будете использовать его постоянно, будь то разработка микросервиса, API для мобильного приложения или полноценного веб-приложения.

Типичные ошибки

Одна из распространенных ошибок — забыть добавить @RestController или @ResponseBody. В таком случае Spring не будет генерировать ответы в формате JSON, и клиенту может вернуться либо пустое тело, либо 404.

Также часто забывают настроить корректные пути (URI), из-за чего запросы не попадают в нужный метод. Не забудьте всегда использовать точные аннотации маршрутов, такие как @GetMapping или @PostMapping.