🥇 Унификация API-ошибок в Spring Boot

Чёткая схема API помогает наладить диалог между провайдером и клиентом, а единый формат ошибок — избавить потребителей от хаоса в коде и лишних поводов для «боли».

🔹 В Spring Boot по умолчанию структура ошибок выглядит так:

{
"timestamp": "2021-15-08T14:32:17.947+0000",
"status": 500,
"error": "Internal Server Error",
"path": "/test"
}

Такая форма ответа не всегда содержит тип ошибки для обработки на клиенте, а также предоставляет мало контекста для формирования пользовательских сообщений.

🔹 Решение: разработать унифицированную структуру, например:

{
"error": {
"type": "USER_NOT_FOUND",
"message": "User with ID 12345 not found.",
"status": 500,
"path": "/integration/apps",
"timestamp": "2021-15-08T14:32:17.947+0000",
"data": {
"userId": "12345"
}
}
}

🔹 Как внедрить:

▪️ Создаём единое исключение AppException:

public final class AppException extends RuntimeException {
private final ErrorType type;
private Map<String, Object> data;
// конструктор и геттеры...
}
public enum ErrorType {
USER_NOT_FOUND(404), AUTHENTICATION_FAILED(401), …;
private final int status;
// геттеры...
}

▪️ Глобальный обработчик:
Используем @ControllerAdvice с @ExceptionHandler(AppException.class) для перехвата ошибок и возвращения QErrorResponse, содержащего нужную структуру

▪️ Обработка всех остальных ошибок:
Создаём свой ErrorController, заменяющий BasicErrorController, и возвращаем данные в таком же формате QErrorResponse:

@RestController
@RequestMapping("${server.error.path:${error.path:/error}}")
public class RestErrorController extends AbstractErrorController {
// логика формирования QErrorResponse…
}

Это гарантирует, что любые ошибки возвращаются в одинаковом формате .

🔹 Почему это важно:

— Унификация ответа облегчает обработку ошибок на клиенте.
— Контекст в data позволяет выдавать более понятные сообщения пользователю.
— Расширяемость дает возможность добавлять новые типы ошибок при сохранении консистентности.

🐸 Библиотека джависта

#буст

🐸 Библиотека джависта

#развлекалово