Единый формат ответа

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

Структура ответа

ApiResponse<T> содержит пять полей:

Автоматическая обёртка

Когда включён параметр response.wrap-enabled, обычное значение из контроллера автоматически становится успешным ответом:

@GetMapping("/{id}")
public UserView get(@PathVariable Long id) {
    return userService.get(id);
}

Вызывать ApiResponse.success(...) вручную в каждом методе не нужно.

Строковые результаты также оборачиваются корректно. Даже если Spring выбрал StringHttpMessageConverter, SmartMVC запишет JSON, а не попытается вывести объект как обычную строку.

Типы, которые не оборачиваются

Следующие значения возвращаются без изменений:

• объект, который уже является ApiResponse;
• byte[];
• Spring Resource;
• StreamingResponseBody;
• ProblemDetail.

Эти типы обычно применяются для файлов, двоичных данных, потоковой передачи или стандартного описания проблемы. Дополнительная JSON-обёртка для них была бы неуместна.

Создание ответа вручную

Если нужно задать своё сообщение или код результата, используйте фабричные методы:

return ApiResponse.success("User created", userView);

return ApiResponse.failure(
        "ORDER_CLOSED",
        "The order is already closed",
        Map.of("orderId", orderId)
);

Если контроллер уже вернул ApiResponse, SmartMVC не будет оборачивать его повторно.

Результат типа void

По умолчанию методы с результатом void или Void превращаются в успешный ответ с data: null.

spring:
  smart:
    mvc:
      response:
        wrap-void: false

После отключения этого параметра для void единое тело ответа больше не создаётся.

Результат с пагинацией

PageResult<T> — универсальная модель, которая не зависит от базы данных или конкретного плагина пагинации:

PageResult<UserView> result = new PageResult<>(
        users,
        total,
        page,
        pageSize
);

Она предоставляет:

• items — данные текущей страницы;
• total — общее количество записей;
• page — номер текущей страницы;
• pageSize — количество элементов на странице;
• totalPages — число страниц, вычисленное из общего количества и размера страницы.

Почему Long по умолчанию становится строкой

JavaScript не способен точно представить все 64-битные целые числа. Поэтому стандартная конфигурация сериализует long и Long как строки:

spring.smart.mvc.response.long-as-string: true

Если все клиенты гарантированно умеют безопасно работать с 64-битными целыми, параметр можно отключить.

Параметры

spring:
  smart:
    mvc:
      response:
        wrap-enabled: true
        wrap-void: true
        success-message: success
        long-as-string: true

Если отключить wrap-enabled, бин автоматической обработки ответов не будет зарегистрирован, и Spring MVC вернёт значения контроллеров без изменений.