Проверка входных данных

Клиент может прислать что угодно: пустой заголовок, текст на мегабайт, отрицательное число. Проверять каждое поле через if долго и легко что-то пропустить. Jakarta Validation позволяет описать правила аннотациями прямо на полях — @NotBlank, @Size, @Email — а проверку выполнит фреймворк. В Quarkus стандарт реализует Hibernate Validator.

Подключение расширения

В папке проекта выполните:

./mvnw quarkus:add-extension -Dextensions="hibernate-validator"

В pom.xml появится зависимость quarkus-hibernate-validator. Dev mode заметит изменение pom.xml и перезапустит приложение; в строке Installed features появится hibernate-validator.

Правила на записи

Аннотации ставят на компоненты записи NewPost:

// src/main/java/com/example/blog/NewPost.java
package com.example.blog;
 
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
 
public record NewPost(
        @NotBlank
        @Size(max = 100)
        String title,
 
        @NotBlank(message = "Текст поста не может быть пустым")
        String body) {
}

Заголовок не должен быть пустым и длиннее 100 символов, текст — пустым. В message можно задать своё сообщение об ошибке.

Включение проверки в ресурсе

Чтобы Quarkus проверил тело запроса, перед параметром ставят @Valid (импорт jakarta.validation.Valid):

// src/main/java/com/example/blog/PostResource.java
@POST
public Response create(@Valid NewPost newPost) {
    Post post = postService.create(newPost.title(), newPost.body());
    return Response.created(URI.create("/posts/" + post.id()))
            .entity(post)
            .build();
}

Если данные неверны, метод даже не вызывается — Quarkus сразу отвечает 400:

curl -i -X POST http://localhost:8080/posts \
     -H "Content-Type: application/json" \
     -H "Accept-Language: ru" \
     -d '{"title":"","body":""}'

HTTP/1.1 400 Bad Request
Content-Type: application/json
validation-exception: true

{"title":"Constraint Violation","status":400,"violations":[
  {"field":"create.newPost.title","message":"не должно быть пустым"},
  {"field":"create.newPost.body","message":"Текст поста не может быть пустым"}]}

В field указан метод, параметр и поле, в message — текст ошибки. JSON разбит на строки для удобства чтения.

Язык сообщений

Стандартные сообщения переведены на многие языки. Quarkus выбирает язык по заголовку Accept-Language, если этот язык перечислен в настройках:

# src/main/resources/application.properties
quarkus.default-locale=en
quarkus.locales=en,ru

Без заголовка сообщения будут на английском: must not be blank.

Основные аннотации

Проверка параметров

Аннотации работают и на параметрах пути и запроса:

// src/main/java/com/example/blog/PostResource.java
@GET
public List<Post> list(@QueryParam("search") String search,
                       @QueryParam("limit") @DefaultValue("10") @Max(50) int limit) {
    // ...
}

Запрос /posts?limit=100 получит 400 с сообщением must be less than or equal to 50 для поля list.limit.

Частая ошибка

Без @Valid аннотации на записи ничего не проверяют. Пустой пост молча сохранится:

curl -i -X POST http://localhost:8080/posts -H "Content-Type: application/json" -d '{"title":"","body":""}'

HTTP/1.1 201 Created

{"id":3,"title":"","body":""}

Аннотации на полях только описывают правила, а запускает проверку именно @Valid у параметра метода.