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. Так что валидация — это не роскошь, а необходимость!