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

Что такое Whitelabel-страница ошибки в Spring Boot

Когда Spring Boot обнаруживает ошибку, он перенаправляет запрос на URL /error. Если в приложении нет пользовательского представления для этого пути, Spring Boot отображает встроенную Whitelabel-страницу ошибки.

Whitelabel показывает дату и время ошибки с часовым поясом, тип ошибки и код состояния. В примере выше указано 404 — потому что в демонстрационном приложении нет мэппинга для URL /products.

Большая часть данных на странице берётся из набора атрибутов ошибки, к которым имеет доступ view в Spring Boot:

• error: причина ошибки (короткое текстовое описание).
• timestamp: дата и время возникновения ошибки.
• status: код статуса HTTP.
• exception: имя класса корневого исключения (если есть исключение).
• message: сообщение исключения (если есть исключение).
• errors: результаты BindingResult (например, валидация полей).
• trace: стектрейс исключения (только при наличии исключения).
• path: путь URL, на котором возникла ошибка.

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

Создание страницы ошибки с помощью Thymeleaf

Рекомендуемая практика — иметь один общий шаблон ошибки в каталоге шаблонов вашего приложения. Имя файла зависит от движка шаблонов: для Thymeleaf это обычно error.html, для JSP — error.jsp.

В примере ниже рассматривается Thymeleaf-шаблон error.html, который следует положить в папку templates внутри resources: src/main/resources/templates/error.html.

Файл error.html (пример)

  
    
    
    
  
  
    

      
Произошла ошибка...
      
      
Проблема возникла при обработке страницы
        ().
      

      

      Вернуться на главную
    
  

Этот шаблон выполняет несколько задач:

• Уведомляет пользователя о факте ошибки.
• Показывает URL-запрос (path), вызвавший ошибку.
• Отображает код статуса и сопровождающий его текст (status и error) простыми словами.
• При наличии исключения показывает сообщение message (короткое и информативное).
• Даёт ссылку для возврата на главную и использует стили и изображения, чтобы страница выглядела как часть приложения.

Лучшие практики для страницы ошибки

• Показывайте пользователю минимально необходимую информацию: путь, краткое объяснение, действие (например, ссылка на главную или форму обратной связи).
• Не показывайте стектрейс или внутренние детали в продакшене — это раскрывает архитектуру и уязвимости.
• Логируйте полные данные на сервере: стектрейсы, контекст запроса, идентификаторы сессий.
• Поддерживайте отдельные страницы для популярных кодов (404, 500). Spring Boot автоматически ищет файлы error/404.html, error/500.html в папке static или templates.
• Делайте дизайн консистентным с остальным приложением — пользователю важна непрерывность опыта.

Альтернативные подходы

• Использовать ErrorController и собственный контроллер, реализующий логику показа ошибок (подходит, если нужна динамика или мультиязычность).
• Обрабатывать исключения через @ControllerAdvice и возвращать ModelAndView с нужным шаблоном.
• Размещать статические страницы ошибок в src/main/resources/static/error/404.html, чтобы контейнер отдавал их без загрузки шаблонизатора.
• Для API (JSON) вернуть представление ошибки в формате JSON, например при запросах с Accept: application/json.

Когда кастомная страница не решит проблему

• Если ошибка связана с недоступностью самого приложения (например, OutOfMemoryError на этапе старта), то внутри приложения показать страницу нельзя — требуется внешний шлюз (reverse proxy) или статический fallback на уровне веб-сервера.
• Если проблема возникает до того, как конфигурация шаблонов загружена, статические страницы в /static/error/ будут предпочтительнее.

Рекомендации по безопасности и конфиденциальности

• По умолчанию не включайте trace в ответы для публичных пользователей. Trace полезен в разработке, но опасен в проде.
• Не включайте подробные сообщения об ошибках, содержащие данные пользователей.
• Логируйте PII (персональные данные) осторожно и в соответствии с политиками конфиденциальности и GDPR: храните минимум данных, ограничивайте доступ к логам.

Факт-бокс: полезные коды HTTP

• 400 — Bad Request (неверный запрос)
• 401 — Unauthorized (требуется аутентификация)
• 403 — Forbidden (доступ запрещён)
• 404 — Not Found (страница не найдена)
• 500 — Internal Server Error (внутренняя ошибка сервера)

Эти коды часто обрабатывают отдельными страницами или сообщениями.

Критерии приёмки

• Страница ошибки открывается при переходе на несуществующий URL (/products, /unknown).
• Код ответа соответствует реальной ошибке (404, 500 и т. д.).
• В продакшене пользователь не видит стектрейсов и внутренних исключений.
• На странице доступна ссылка для возврата и/или способ связаться с техподдержкой.
• Событие ошибки полноценно логируется на сервере с идентификатором инцидента.

Чек-лист для ролей

• Разработчик:
  • Создать templates/error.html.
  • Обеспечить логирование стектрейсов в логах.
  • Реализовать @ControllerAdvice для специфичных ошибок (по необходимости).
• Дизайнер:
  • Обеспечить консистентный стиль и понятные CTA (кнопки действия).
  • Подготовить иконки и фоновые изображения с оптимизированным размером.
• Операции/Сайт-админ:
  • Настроить мониторинг на рост количества 5xx ошибок.
  • Настроить хранение логов и доступы к ним.

Шаблоны и дополнительные сниппеты

• Статические страницы: положите файлы в src/main/resources/static/error/404.html и 500.html для ситуаций, когда приложение не может загрузить шаблонизатор.

• Пример простого @ControllerAdvice, возвращающего шаблон ошибки для исключений:

@ControllerAdvice
public class GlobalExceptionHandler {

  @ExceptionHandler(Exception.class)
  public ModelAndView handleException(HttpServletRequest req, Exception ex) {
    ModelAndView mav = new ModelAndView("error");
    mav.addObject("message", ex.getMessage());
    mav.addObject("path", req.getRequestURI());
    return mav;
  }
}

Мини‑методология внедрения

1. Добавьте базовый шаблон templates/error.html.
2. Тестируйте локально: запросы на несуществующие URL должны возвращать ваш шаблон.
3. Добавьте отдельные страницы для 404 и 500 при необходимости (error/404.html, error/500.html).
4. Отключите показ trace в production (application.properties: server.error.include-stacktrace=never).
5. Настройте логирование и мониторинг (Sentry, ELK, Prometheus/Alertmanager).

Краткий глоссарий

• Whitelabel: встроенная дефолтная страница ошибки Spring Boot.
• ErrorController: интерфейс/механизм, который обрабатывает путь /error.
• @ControllerAdvice: аннотация для глобальной обработки исключений.

Диаграмма принятия решения (Mermaid)

flowchart TD
  A[Ошибка в приложении] --> B{Доступен шаблонизатор?}
  B -- Да --> C[Отобразить templates/error.html]
  B -- Нет --> D[Отдать static/error/500.html]
  C --> E{Код ошибки}
  E -- 404 --> F[Отобразить error/404.html]
  E -- 500 --> G[Отобразить error/500.html]

Подведение итогов

Кастомизация страницы ошибки в Spring Boot делает приложение более дружественным к пользователю и безопасным. Используйте шаблон error.html для общего вида, отдельные страницы для часто встречающихся кодов, логируйте технические детали и скрывайте их от конечного пользователя. При необходимости применяйте ErrorController или @ControllerAdvice для более тонкой обработки.

Важно: в продакшене никогда не показывайте стектрейс и подробности исключений обычным пользователям — вместо этого логируйте их в защищённые хранилища и предоставляйте пользователю понятный текст с инструкциями.