Створення 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.