Обробка параметрів та тіла запиту (Query Parameters, Path Variables)

Коли сервер надає API, параметри й дані запитів відіграють ключову роль у керуванні ресурсами. Сьогодні розберемо:

1. Обробку Query Parameters: фільтри й сортування.
2. Роботу з Path Variables: динамічні сегменти URI.
3. Як обробляти помилки, пов'язані з параметрами.

І, звісно, напишемо код! Бо теорія без практики — як метод без реалізації.

Що таке Query Parameters?

Почнемо з Query Parameters. Це параметри, які передає клієнт у рядку запиту після символу ?. Вони використовуються для фільтрації, сортування, пошуку даних та інших уточнень запиту.

Приклад URL з Query Parameters:

https://api.myapp.com/products?category=electronics&sort=price&order=asc

• category=electronics: вказує фільтр по категорії «електроніка».
• sort=price: сигналізує, що ми сортуємо за ціною.
• order=asc: додає уточнення, що сортування зростаюче.

Анотація @RequestParam

Щоб обробити Query Parameters у Spring, використовується анотація @RequestParam. Давайте подивимось на приклад коду:

@RestController
@RequestMapping("/products")
public class ProductController {

    @GetMapping
    public List<Product> getProducts(
            @RequestParam(required = false) String category,
            @RequestParam(defaultValue = "name") String sort,
            @RequestParam(defaultValue = "asc") String order
    ) {
        // Логіка фільтрації, сортування
        return productService.getProducts(category, sort, order);
    }
}

• @RequestParam(required = false): параметр не обов'язковий. Якщо клієнт не передасть category, він буде рівний null.
• defaultValue: задає значення за замовчуванням, якщо параметр відсутній у запиті.

Коли запит надсилається на /products?category=clothing, у методі getProducts змінна category буде мати значення "clothing", а sort і order приймуть значення за замовчуванням.

Що таке Path Variables?

Path Variables (змінні шляху) — це частини URI, які містять динамічні значення.

Уявіть, що у нас є REST API для керування товарами, і нам потрібно отримати товар за його ID. Ось приклад URI:

https://api.myapp.com/products/42

Тут 42 — це ідентифікатор товару, і ми хочемо витягнути його з шляху. Для цього використовується анотація @PathVariable.

Анотація @PathVariable

Spring дозволяє "діставати" ці значення з URI таким чином:

@RestController
@RequestMapping("/products")
public class ProductController {

    @GetMapping("/{id}")
    public Product getProductById(@PathVariable Long id) {
        // Логіка отримання продукту за ID
        return productService.getProductById(id);
    }
}

Коли клієнт надішле запит GET /products/42, змінна id отримає значення 42.

Об'єднуємо @RequestParam і @PathVariable

А тепер, як кажуть програмісти, йдемо на рівень вище. Ми можемо їх поєднувати! Наприклад, можна зробити таку комбінацію:

• URI містить динамічне значення (id), щоб ідентифікувати ресурс.
• Query Parameters використовуються для додаткової настройки.

Приклад: отримання замовлень користувача з фільтром

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

    @GetMapping("/{userId}/orders")
    public List<Order> getUserOrders(
            @PathVariable Long userId,
            @RequestParam(required = false) String status,
            @RequestParam(defaultValue = "date") String sort
    ) {
        // Логіка фільтрації замовлень користувача
        return orderService.getUserOrders(userId, status, sort);
    }
}

Запит:

GET /users/101/orders?status=completed&sort=price

У цьому прикладі:

• userId буде рівним 101.
• status буде рівним "completed".
• sort буде рівним "price".

Валідуємо параметри запиту

Не завжди клієнти надсилатимуть нам коректні дані. Наприклад, що робити, якщо в запиті ID користувача вказано як abc, а це явно некоректно?

Обробка помилок

Spring автоматично поверне помилку, якщо @PathVariable або @RequestParam не відповідає очікуваному типу. Наприклад:

@GetMapping("/{id}")
public Product getProductById(@PathVariable Long id) {
    return productService.getProductById(id);
}

Запит GET /products/abc спричинить:

HTTP 400 Bad Request

Щоб зробити обробку помилок більш витонченою, можна використати анотацію @ExceptionHandler:

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    public ResponseEntity<String> handleTypeMismatch(MethodArgumentTypeMismatchException ex) {
        return ResponseEntity
                .badRequest()
                .body("Невірний параметр: " + ex.getName());
    }
}

Тепер помилка буде більш дружньою для клієнта:

HTTP 400 Bad Request
Body: Невірний параметр: id

Практика: Приклад REST API для роботи з книгами

Давайте створимо REST API для роботи з книгами. API дозволить:

1. Отримувати книгу за ID.
2. Шукати книги за жанром із сортуванням.

Клас сутності Book

@Entity
public class Book {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String title;
    private String genre;
    private double price;

    // Геттери і сеттери
}

Репозиторій BookRepository

@Repository
public interface BookRepository extends JpaRepository<Book, Long> {

    List<Book> findByGenre(String genre, Sort sort);
}

Сервіс BookService

@Service
public class BookService {

    @Autowired
    private BookRepository bookRepository;

    public Book getBookById(Long id) {
        return bookRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("Книга не знайдена!"));
    }

    public List<Book> getBooksByGenre(String genre, String sortField) {
        Sort sort = Sort.by(Sort.Direction.ASC, sortField);
        return bookRepository.findByGenre(genre, sort);
    }
}

Контролер BookController

@RestController
@RequestMapping("/books")
public class BookController {

    @Autowired
    private BookService bookService;

    @GetMapping("/{id}")
    public Book getBookById(@PathVariable Long id) {
        return bookService.getBookById(id);
    }

    @GetMapping
    public List<Book> getBooksByGenre(
            @RequestParam(required = false) String genre,
            @RequestParam(defaultValue = "title") String sort
    ) {
        return bookService.getBooksByGenre(genre, sort);
    }
}

Тепер:

• GET /books/1 поверне книгу з ID 1.
• GET /books?genre=fantasy&sort=price поверне всі книги жанру "fantasy", відсортовані за ціною.

Типові помилки та їх вирішення

1. @PathVariable відсутній в URI. Переконайтеся, що змінна шляху вказана у маршруті (наприклад, /{id}).
2. Неправильний тип даних параметра. Якщо id очікує Long, а клієнт передав рядок, буде помилка 400.
3. Відсутність обов'язкових Query Parameters. Переконайтеся, що ви використовуєте required = false, якщо параметр необов'язковий.

На цьому етапі ви опанували роботу з Query Parameters і Path Variables. Тепер ваші REST API стануть більш функціональними й гнучкими. Тримайте курс на наступне заняття і не забувайте тестувати API!