Bean Validation API: анотації @NotNull, @Min, @Max тощо.

"У ідеальному світі всі користувачі надсилали б тільки правильні дані..." — звучить як початок казки. Насправді ж ми зіштовхуємося з описками у формах, забутими обов'язковими полями і навіть спробами SQL-ін'єкцій у полі для імені. І тут на сцену виходить валідація даних — перша лінія оборони будь-якого веб-застосунку.

У попередній лекції ми мимохіть згадували Bean Validation API — набір спеціальних анотацій, які перетворюють перевірку даних з головного болю на простий і зрозумілий процес. Тепер давай познайомимось з ним детальніше.

Що таке Bean Validation API?

Bean Validation API — це специфікація Java (JSR 380), яка надає набір анотацій для визначення правил валідації. Вона працює у зв'язці з Hibernate Validator, який часто використовується як реалізація цієї специфікації в Spring-додатках.

Bean Validation дозволяє виконувати валідацію:

• Полів об'єктів (наприклад, сутностей бази даних або DTO).
• Вхідних параметрів методів.
• Конфігурацій класів.

Класичний приклад валідації: потрібно переконатися, що користувач не залишив поле "email" порожнім і ввів його у правильному форматі. Замість того щоб писати ручну перевірку (старий добрий if/else), можеш просто додати до поля анотацію @NotNull.

Як це працює?

Коли Spring обробляє запити або дані, він автоматично перевіряє об'єкт, аннотований правилами Bean Validation. Якщо дані не відповідають правилам, Spring викидає виключення, яке ми можемо обробити (наприклад, повернути користувачу повідомлення "Ей, твій email неправильний!").

Основні анотації Bean Validation API

@NotNull

Ця анотація гарантує, що значення поля не є null. Однак зверни увагу: вона не перевіряє порожнечу рядка. Наприклад:

import jakarta.validation.constraints.NotNull;

public class UserDTO {
    @NotNull(message = "Ім'я користувача не може бути пустим!")
    private String name;

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

Якщо поле name виявиться рівним null, то Spring викине помилку валідації з повідомленням "Ім'я користувача не може бути пустим!".

@Size

@Size використовується для перевірки розміру рядків, колекцій, масивів та інших об'єктів. Наприклад, щоб переконатися, що ім'я користувача складається мінімум з 3 символів, а максимум з 50:

import jakarta.validation.constraints.Size;

public class UserDTO {
    @Size(min = 3, max = 50, message = "Ім'я має містити від 3 до 50 символів.")
    private String username;

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

Зверни увагу: якщо хочеш перевірити лише довжину рядка, використовуй @Size. Якщо ж потрібно перевірити порожнечу рядка, додай до цього ще @NotBlank.

@Min и @Max

Ці анотації використовуються для числових полів, щоб задати їх мінімальні і максимальні значення.

Приклад: вік користувача має бути від 18 до 65:

import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.Max;

public class UserDTO {
    @Min(value = 18, message = "Вік не може бути менше 18.")
    @Max(value = 65, message = "Вік не може бути більше 65.")
    private int age;

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

@Pattern

Якщо ти любиш регулярні вирази, то @Pattern тобі точно знадобиться. Ця анотація перевіряє рядки на відповідність заданому регулярному виразу.

Приклад: перевірка формату номера телефону

import jakarta.validation.constraints.Pattern;

public class UserDTO {
    @Pattern(regexp = "\\+\\d{1,3}-\\d{9,15}", message = "Телефон має бути у форматі +XXX-XXXXXXXXXXXXX.")
    private String phoneNumber;

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

Тут \\+\\d{1,3}-\\d{9,15} означає, що телефон має починатися з +, за яким іде від 1 до 3 цифр, потім дефіс, і далі від 9 до 15 цифр.

@Email

Не можна забувати про поштові адреси! Анотація @Email перевіряє, чи введений рядок дійсно відповідає формату email:

import jakarta.validation.constraints.Email;

public class UserDTO {
    @Email(message = "Введи правильну email-адресу.")
    private String email;

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

@NotBlank и @NotEmpty

Ці анотації спеціалізуються на рядках:

• @NotEmpty перевіряє, щоб рядок не був null і довжина рядка була більше 0.
• @NotBlank додатково перевіряє, щоб рядок не складався лише з пробілів.

Приклад:

import jakarta.validation.constraints.NotBlank;

public class UserDTO {
    @NotBlank(message = "Ім'я не може бути пустим або складатися тільки з пробілів.")
    private String name;

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

Приклад: створення анотованого класу DTO

Зберемо все разом. Уяви, що в нас є форма реєстрації користувача. Користувач має вказати:

• Ім'я (від 3 до 50 символів, не повинно бути порожнім).
• Вік (від 18 до 65).
• Email.
• Пароль (не менше 8 символів).

Код може виглядати так:

import jakarta.validation.constraints.*;

public class UserRegistrationDTO {

    @NotBlank(message = "Ім'я не може бути пустим.")
    @Size(min = 3, max = 50, message = "Ім'я користувача має бути від 3 до 50 символів.")
    private String username;

    @Min(value = 18, message = "Вік не може бути менше 18.")
    @Max(value = 65, message = "Вік не може бути більше 65.")
    private int age;

    @NotBlank(message = "Email обов'язковий для заповнення.")
    @Email(message = "Введи коректну email-адресу.")
    private String email;

    @NotBlank(message = "Пароль обов'язковий для заповнення.")
    @Size(min = 8, message = "Пароль має містити мінімум 8 символів.")
    private String password;

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

Тепер цей об'єкт можна використовувати для валідації даних.

Приклад використання в Spring MVC

Корисно не тільки декларувати правила валідації, а й бачити їх в дії. Уявімо, що ми створюємо контролер для обробки POST-запиту реєстрації:

import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import jakarta.validation.Valid;

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

    @PostMapping("/register")
    public ResponseEntity<String> registerUser(@Valid @RequestBody UserRegistrationDTO userDTO) {
        // Логіка обробки користувача (наприклад, збереження в базу даних)
        return ResponseEntity.ok("Користувач успішно зареєстрований!");
    }
}

Тут:

• Анотація @Valid автоматично запускає перевірку прийомного об'єкта UserRegistrationDTO.
• Якщо дані не відповідають правилам, Spring автоматично повертає помилку (зазвичай код 400 і опис помилки).

Типові помилки

Багато хто робить помилки при використанні Bean Validation API. Ось кілька поширених проблем:

• Забули додати Hibernate Validator у залежності проєкту. Якщо у тебе Spring Boot, ця проблема малоймовірна, бо Hibernate Validator підключений за замовчуванням.
• Неправильні регулярні вирази. Перевіряй свої @Pattern, інакше анотація буде "валити" всі значення.
• Немає анотації @Valid. Ця помилка особливо часта в контролерах — без неї валідація просто не спрацьовує.
• Змішування анотацій. Наприклад, використання @NotNull там, де треба @NotBlank.

Висновки

Валідація даних — це не просто галочка в чек-листі розробника. Це захист цілісності даних і безпеки як користувачів, так і застосунку. Bean Validation API перетворює цей захист на зручний і потужний інструмент, роблячи код чистішим і надійнішим.

Хочеш копнути глибше? Заглянь в офіційну документацію Hibernate Validator. Там знайдеш ще більше цікавих можливостей.

І наостанок: довіряй, але перевіряй! Введення користувача інколи може бути як скриня Пандори — ніколи не знаєш, що там зустрінеш. Від нешкідливої описки до підступного DROP TABLE. Тож валідація — це не розкіш, а необхідність!