Гид по технологиям

Кастомизация страницы ошибок в Spring Boot

• 5 min read • Разработка • Обновлено 24 Apr 2026
Кастомизация страницы ошибок Spring Boot
Кастомизация страницы ошибок Spring Boot

MacBook с экраном страницы ошибки

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

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

Стандартная Whitelabel‑страница ошибок Spring Boot

Когда приложение Spring Boot сталкивается с ошибкой, фреймворк перенаправляет запрос на URL /error. Если по этому пути не найден view, отображается Whitelabel‑страница ошибки:

Стандартная Whitelabel-страница ошибки Spring Boot

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

Большая часть информации на Whitelabel берётся из набора атрибутов ошибки. Представления ошибок в Spring Boot имеют доступ к следующим атрибутам:

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

Создание страницы ошибок с Thymeleaf

В приложении должен быть один шаблон ошибки, размещённый в каталоге templates. Расширение файла зависит от движка шаблонов: для JSP — error.jsp, для Thymeleaf — error.html и т.д. В примере используется Thymeleaf, поэтому файл называется error.html и находится в src/main/resources/templates.

Файл error.html

  
  
   
          Error  
       
   
   
       
       
An error has occurred...
  
         
       
There seems to be a problem with the page you requested   
       ().
  
       
  
       
  
       Back to home  
     
 

Этот шаблон выполняет важные задачи: сообщает об ошибке, показывает путь запроса, указывает код статуса и краткое объяснение через атрибут error. При наличии исключения отображается сообщение, а ссылка внизу возвращает пользователя на главную страницу. В шаблоне используются CSS и изображения для стилизации.

Кастомизированная страница ошибки приложения

Сделайте страницу удобной и безопасной

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

  • Показывайте только нужные атрибуты: path, status, короткое сообщение. trace и детали стека не нужны пользователю.
  • Не раскрывайте внутренние данные и PII. Используйте общие фразы, а подробности — в логах на сервере.
  • Для ошибок 4xx дайте понятное объяснение и инструкцию (проверьте URL, войдите в систему). Для 5xx — предложите перезагрузить страницу и сообщите, что команда получила уведомление.

Важно: храните полные трассировки только в защищённых логах. На странице пользователя показывайте упрощённую информацию.

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

  • Статичная HTML‑страница: положите error.html в static/ — подойдёт для простых сайтов без шаблонизатора.
  • Другие шаблонизаторы: Freemarker, Mustache, JSP — Spring Boot найдёт error.* автоматически.
  • Разделение для API и UI: для браузерных запросов отдавайте HTML, для API — JSON. Используйте ContentNegotiation или контроллеры с @ControllerAdvice для REST.

Пример простого обработчика для REST‑API, который возвращает JSON вместо HTML:

@ControllerAdvice
public class RestExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(Exception.class)
    protected ResponseEntity handleAllExceptions(Exception ex, WebRequest request) {
        Map body = new LinkedHashMap<>();
        body.put("timestamp", new Date());
        body.put("status", HttpStatus.INTERNAL_SERVER_ERROR.value());
        body.put("error", "Internal Server Error");
        body.put("message", ex.getMessage());
        body.put("path", ((ServletWebRequest)request).getRequest().getRequestURI());
        return new ResponseEntity<>(body, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}
Когда кастомизация может не сработать
  • Клиент ожидает JSON, а вы возвращаете HTML — приложение клиента сломается. Разделяйте обработку по типу запроса.
  • Если шаблон лежит в неправильной папке (не в resources/templates для Thymeleaf), Spring будет показывать Whitelabel.
  • Если ваш веб‑сервер (NGINX, CDN) обрабатывает ошибки раньше приложения, шаблон не отобразится.
Мини‑методика внедрения
  1. Поместите error.html в src/main/resources/templates.
  2. Покройте кейсы: 404, 403, 500. Создайте дружелюбные сообщения.
  3. Для API добавьте @ControllerAdvice, возвращающий JSON.
  4. Логируйте полные детали на сервере и свяжите id инцидента с сообщением на фронте.
  5. Тестируйте: UI (браузер), API (curl/postman), интеграционные тесты.
Check‑лист ролей
  • Разработчик:
    • Шаблон размещён в resources/templates.
    • Проверены локализации сообщений.
    • Добавлен unit/integration тест.
  • DevOps:
    • Логи централизованы (ELK, Splunk или подобное).
    • CDN/NGINX не блокирует отображение кастомной страницы.
  • Security:
    • На странице нет stack trace и PII.
    • Логи доступны только авторизованному персоналу.
  • UX:
    • Сообщение понятно и содержит путь к действию (обновить, связаться с поддержкой).
Шпаргалка конфигурации
  • Стандартный путь шаблона: src/main/resources/templates/error.html
  • Для отключения Whitelabel (при явной подстановке своего обработчика): server.error.whitelabel.enabled=false
  • Контент‑negotiation: убедитесь, что Accept заголовки корректно обрабатываются при выборе HTML vs JSON
Критерии приёмки
  • Пользователь видит понятное сообщение об ошибке.
  • Для API возвращается корректный JSON с полями timestamp, status, error, message, path.
  • Стек‑трейсы не видны в UI, но есть в логах с уникальным id инцидента.
  • Тесты покрывают 404 и 500 сценарии.
Безопасность и приватность
  • Не выводите trace и internal exception messages на публичную страницу.
  • Не включайте в сообщения пользовательские данные (PII). Вместо этого логируйте их в защищённом хранилище.
  • Ограничьте доступ к логам и внедрите уведомления о 5xx ошибках.
Примеры и сравнение подходов
СценарийHTML (Thymeleaf)JSON (REST)
Браузерный сайтПодходит — отображает стиль и ссылкиНеподходящт — пользователь увидит необработанный JSON
SPA/JS клиентПодходит, если SPA ожидает HTMLЧасто требуется JSON для клиентской обработки
Микросервис APIНе рекомендуетсяРекомендуется — структурированный ответ
Итог
Кастомизация страницы ошибок в Spring Boot — простая, но важная часть качества приложения. Поместите единый шаблон ошибок в resources/templates для HTML‑клиентов и реализуйте @ControllerAdvice для API. Не раскрывайте внутренние детали пользователям, логируйте их и тестируйте обработку ошибок.
Ключевые шаги: создать шаблон error.html, различать HTML/JSON клиенты, логировать детали, обеспечить понятный UX и защиту приватных данных.


      

      

        

  Поделиться:
  
    X/Twitter
  
  
    Facebook
  
  
    LinkedIn
  
  
    Telegram
  
  


      


      

  
  

    
Автор

    

      Редакция
    

  




      

      

  

    Похожие материалы
  

  

    
      

        
        
        

          Несколько аккаунтов Skype: Multi Skype Launcher
        

        

          

            
              Программное обеспечение
            
            
          

          

            Несколько аккаунтов Skype: Multi Skype Launcher
          

        

      

    
      

        
        
        

          Журнал для работы: повысить продуктивность
        

        

          

            
              Productivity
            
            
          

          

            Журнал для работы: повысить продуктивность
          

        

      

    
      

        
        
        

          Персональные звуки уведомлений на Android
        

        

          

            
              Android.
            
            
          

          

            Персональные звуки уведомлений на Android
          

        

      

    
      

        
        
        

          Скачивание шоу Hulu для офлайн‑просмотра
        

        

          

            
              Стриминг
            
            
          

          

            Скачивание шоу Hulu для офлайн‑просмотра
          

        

      

    
      

        
        
        

          Microsoft Start: персонализированная новостная лента
        

        

          

            
              Новости
            
            
          

          

            Microsoft Start: персонализированная новостная лента
          

        

      

    
      

        
        
        

          Как изменить имя в Epic Games быстро
        

        

          

            
              Гайды
            
            
          

          

            Как изменить имя в Epic Games быстро