Валидация данных в Spring Boot

Валидация в Controller

Сначала данные попадают в контроллер. У входящего HTTP-запроса возможно проверить следующие параметры:

• тело запроса
• переменные пути (например, id в /foos/{id})
• параметры запроса

Рассмотрим каждый из них подробнее.

Валидация тела запроса

Тело запроса POST и PUT обычно содержит данные в формате JSON. Spring автоматически сопоставляет входящий JSON с объектом Java.

Проверяем соответствует ли входящий Java объект нашим требованиям.

public class PersonDto {

    private Long id;

    @NotBlank
    private String name;

    @Min(1)
    @Max(10)
    private int numberBetweenOneAndTen;

    @Pattern(regexp = "^((25[0-5]|(2[0-4]|1[0-9]|[1-9]|)[0-9])(\\.(?!$)|$)){4}$")
    private String ipAddress;

    // getters and setters

}

• Поле name не должно быть пустым или null.
• Поле numberBetweenOneAndTen должно быть от 1 до 10, включительно.
• Поле ipAddress должно содержать строку в формате IP-адреса.

Достаточно добавить для входящего параметра personDto аннотацию @Valid, чтобы передать объект на валидацию, прежде чем делать с ним что-то еще.

@RestController
@RequestMapping("/api/person")
public class PersonController {

    @PostMapping
    public ResponseEntity<String> valid(@Valid @RequestBody PersonDto personDto) {
        return ResponseEntity.ok("valid");
    }

}

Вызываем наш POST метод и передаем в него не валидные данные.

Postman возвращает нам ошибку, а в консоли получаем исключение, которое сообщает нам что у нас 2 ошибки валидации.

Исключение MethodArgumentNotValidException выбрасывается, когда объект не проходит проверку. По умолчанию, Spring переведет это исключение в HTTP статус 400.

Исключение информативное, но очень тяжелое для восприятия, пользователь при этом не получает никакой информации об ошибке. Далее мы рассмотрим, как это исправить.

Проверка переменных пути и параметров запроса

При проверке переменных пути и параметров запроса не проверяются сложные Java-объекты, так как path-переменные и параметры запроса являются примитивными типами, такими как int, или их аналогами: Integer или String.

Вместо аннотации поля класса, как описано выше, добавляют аннотацию ограничения (в данном случае @Min) непосредственно к параметру метода в контроллере:

@Validated
@RestController
@RequestMapping("/api/person")
public class PersonController {

    // ... ... ... ... ...

    @GetMapping("{id}")
    public ResponseEntity<String> getById(
            @PathVariable("id") @Min(0) int personId
    ) {
        return ResponseEntity.ok("valid");
    }

    @GetMapping
    public ResponseEntity<String> getByName(
            @RequestParam("name") @NotBlank String name
    ) {
        return ResponseEntity.ok("valid");
    }

}

Обратите внимание, что необходимо добавить @Validated в контроллер на уровне класса, чтобы проверять параметры метода. В этом случае аннотация @Validated устанавливается на уровне класса, даже если она присутствует на методах.

В отличии валидации тела запроса, при неудачной проверки параметра вместо метода MethodArgumentNotValidException будет выброшен ConstraintViolationException. По умолчанию последует ответ со статусом HTTP 500 (Internal Server Error), так как Spring не регистрирует обработчик для этого исключения по умолчанию.

Валидация в сервисном слое

Можно проверять данные на любых компонентах Spring. Для этого используется комбинация аннотаций @Validated и @Valid.

@Service
@Validated
public class PersonService {

    public void save(@Valid PersonDto personDto) {
        // do something
    }

}

Аннотация @Validated устанавливается только на уровне класса, так что не ставьте ее на метод в данном случае.

Казалось бы, пример такой же как и в контроллере и логично ожидать MethodArgumentNotValidException, но будет выброшен ConstraintViolationException и 500 ошибка.

Валидация сущностей JPA

Persistence Layer – это последняя линия проверки данных. По умолчанию Spring Data использует Hibernate, который поддерживает Bean Validation из коробки.

Допустим, необходимо хранить объекты нашего класса PersonDto в базе данных.

Когда репозиторий пытается сохранить не валидный PersonDto, чьи аннотации ограничений нарушаются, выбрасывается ConstraintViolationException.

Bean Validation запускается Hibernate только после того как EntityManager вызовет flush.

Чтобы отключить Bean Validation в репозиториях, достаточно установить свойство Spring Boot spring.jpa.properties.javax.persistence.validation.mode равным null.

Конкретизация ошибок

Когда проверка не удается, лучше вернуть клиенту понятное сообщение об ошибке. Для этого необходимо вернуть структуру данных с сообщением об ошибке для каждой проверки, которая не прошла валидацию.

Сначала нужно определить эту структуру данных. Назовем ее ValidationErrorResponse и она содержит список объектов Violation:

@Getter
@RequiredArgsConstructor
public class ValidationErrorResponse {

    private final List<Violation> violations;

}

@Getter
@RequiredArgsConstructor
public class Violation {

    private final String fieldName;
    private final String message;

}

Затем создадим глобальный ControllerAdvice, который обрабатывает все ConstraintViolationExventions, которые пробрасываются до уровня контроллера. Чтобы отлавливать ошибки валидации и для тел запросов, мы также будем перехватывать и MethodArgumentNotValidExceptions:

@ControllerAdvice
public class ErrorHandlingControllerAdvice {

    @ResponseBody
    @ExceptionHandler(ConstraintViolationException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ValidationErrorResponse onConstraintValidationException(
            ConstraintViolationException e
    ) {
        final List<Violation> violations = e.getConstraintViolations().stream()
                .map(
                        violation -> new Violation(
                                violation.getPropertyPath().toString(),
                                violation.getMessage()
                        )
                )
                .collect(Collectors.toList());
        return new ValidationErrorResponse(violations);
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ResponseBody
    public ValidationErrorResponse onMethodArgumentNotValidException(
            MethodArgumentNotValidException e
    ) {
        final List<Violation> violations = e.getBindingResult().getFieldErrors().stream()
                .map(error -> new Violation(error.getField(), error.getDefaultMessage()))
                .collect(Collectors.toList());
        return new ValidationErrorResponse(violations);
    }

}

Здесь информацию о нарушениях из исключений переводится в нашу структуру данных ValidationErrorResponse.

Можно изменить сообщение об ошибке с помощью параметра message у аннотации.

@Pattern(
        regexp = "^((25[0-5]|(2[0-4]|1[0-9]|[1-9]|)[0-9])(\\.(?!$)|$)){4}$",
        message = "Не соответствует формату IP адреса"
)
private String ipAddress;

Валидация конфигурации приложения

Spring Boot аннотация @ConfigurationProperties используется для связывания свойств из application.properties с Java объектом.

Данные из application необходимы для стабильной работы приложения. Bean Validation поможет обнаружить ошибку в этих данных при старте приложения.

Допустим имеется следующий конфигурационный класс:

@Validated
@ConfigurationProperties(prefix="app.properties")
class AppProperties {

  @NotEmpty
  private String name;

  @Min(value = 7)
  @Max(value = 30)
  private Integer reportIntervalInDays;

  @Email
  private String reportEmailAddress;

  // getters and setters
}

При попытке запуска с недействительным адресом электронной почты получаем ошибку:

***
APPLICATION FAILED TO START
***

Description:

Binding to target org.springframework.boot.context.properties.bind.BindException:
  Failed to bind properties under 'app.properties' to
  io.reflectoring.validation.AppProperties failed:

    Property: app.properties.reportEmailAddress
    Value: manager.analysisapp.com
    Reason: must be a well-formed email address

Action:

Update your application's configuration

Стандартные ограничения

Библиотека javax.validation имеет множество аннотаций для валидации.

Каждая аннотация имеет следующие поля:

• message – указывает на ключ свойства в ValidationMessages.properties, который используется для отправки сообщения в случае нарушения ограничения.
• groups – позволяет определить, при каких обстоятельствах будет срабатывать эта проверка (о группах проверки поговорим позже).
• payload – позволяет определить полезную нагрузку, которая будет передаваться сс проверкой.
• @Constraint – указывает на реализацию интерфейса ConstraintValidator.

Рассмотрим популярные ограничения.

@NotNull и @Null

@NotNull - аннотированный элемент не должен быть null. Принимает любой тип.
@Null - аннотированный элемент должен быть null. Принимает любой тип.

@NotBlank и @NotEmpty

@NotBlank - аннотированный элемент не должен быть null и должен содержать хотя бы один непробельный символ. Принимает CharSequence.
@NotEmpty - аннотированный элемент не должен быть null или пустым. Поддерживаемые типы:

• CharSequence
• Collection. Оценивается размер коллекции
• Map. Оценивается размер мапы
• Array. Оценивается длина массива

@Size

Размер аннотированного элемента должен быть между указанными границами, включая сами границы. null элементы считаются валидными.

Поддерживаемые типы:

• CharSequence. Оценивается длина последовательности символов
• Collection. Оценивается размер коллекции
• Map. Оценивается размер мапы
• Array. Оценивается длина массива

Группы валидаций

Некоторые объекты участвуют в разных вариантах использования.

Возьмем типичные операции CRUD: при обновлении и создании, скорее всего, будет использоваться один и тот же класс. Тем не менее, некоторые валидации должны срабатывать при различных обстоятельствах:

• только перед созданием
• только перед обновлением
• или в обоих случаях

Функция Bean Validation, которая позволяет нам внедрять такие правила проверки, называется “Validation Groups”.

Все аннотации ограничений имеют поле groups. Это поле используется для передачи любых классов, каждый из которых определяет группу проверки.

Для нашего примера CRUD определим два маркерных интерфейса OnCreate и OnUpdate:

public interface Marker {

    interface OnCreate {}

    interface OnUpdate {}

}

Затем используем эти интерфейсы с любой аннотацией ограничения:

public class PersonDto {

  @Null(groups = Marker.OnCreate.class)
  @NotNull(groups = Marker.OnUpdate.class)
  private Long id;

  // ... ... ... ... ...

}

Это позволит убедиться, что id пуст при создании и заполнен при обновлении.

Spring поддерживает группы проверки только с аннотацией @Validated

@Validated
@RestController
@RequestMapping("/api/group-valid/person")
public class PersonControllerGroupValid {

    @PostMapping
    @Validated({Marker.OnCreate.class})
    public ResponseEntity<String> create(@RequestBody @Valid PersonDto personDto) {
        return ResponseEntity.ok("valid");
    }

    @PutMapping
    @Validated(Marker.OnUpdate.class)
    public ResponseEntity<String> update(@RequestBody @Valid PersonDto personDto) {
        return ResponseEntity.ok("valid");
    }

}

Обратите внимание, что аннотация @Validated применяется ко всему классу. Чтобы определить, какая группа проверки активна, она также применяется на уровне метода.

Создание своего ограничения

Если имеющихся аннотаций ограничений недостаточно, то создайте новые.

Напишем валидатор, который будет проверять, что строка начинается с большой буквы.

Сначала создаем пользовательскую аннотацию @CapitalLetter:

@Target({ FIELD })
@Retention(RUNTIME)
@Constraint(validatedBy = CapitalLetterValidator.class)
@Documented
public @interface CapitalLetter {

  String message() default "{CapitalLetter.invalid}";

  Class<?>[] groups() default { };

  Class<? extends Payload>[] payload() default { };

}

Реализация валидатора выглядит следующим образом:

public class CapitalLetterValidator implements ConstraintValidator<CapitalLetter, String> {

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value != null && !value.isEmpty()) {
            return Character.isUpperCase(value.charAt(0));
        }
        return true;
    }

}

Теперь можно использовать аннотацию @CapitalLetter, как и любую другую аннотацию ограничения.

public class PersonDto {

  // ... ... ... ... ...

  @NotBlank
  @CapitalLetter
  private String name;

  // ... ... ... ... ...

}

Принудительный вызов валидации

Для принудительного вызова проверки, без использования Spring Boot, создайте валидатор вручную.

public class ProgrammaticallyValidatingService {

  public void validateInput(PersonDto personDto) {
    ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
    Validator validator = factory.getValidator();
    Set<ConstraintViolation<personDto>> violations = validator.validate(personDto);
    if (!violations.isEmpty()) {
      throw new ConstraintViolationException(violations);
    }
  }

}

Тем не менее, Spring Boot предоставляет предварительно сконфигурированный экземпляр валидатора. Внедрив этот экземпляр в сервис не придется создавать его вручную.

@Service
public class ProgrammaticallyValidatingService {

  private Validator validator;

  public ProgrammaticallyValidatingService(Validator validator) {
    this.validator = validator;
  }

  public void validateInputWithInjectedValidator(PersonDto personDto) {
    Set<ConstraintViolation<PersonDto>> violations = validator.validate(personDto);
    if (!violations.isEmpty()) {
      throw new ConstraintViolationException(violations);
    }
  }

}

Резюмирую

Валидация это неотъемлимая часть бизнес логики. Используя зависимость spring-boot-starter-validation, мы можем облегчить себе работу.

Валидацию делают при переходе данных из одного архитектурного слоя в другой, чтобы не разрошить логику принимаемого слоя. Также можно настроить валидацию конфигурации приложения.

Стоит возвращать клиенту понятное описание ошибки валидации, используя @ControllerAdvice.