Что такое страница ошибки Whitelabel? Полное техническое руководство

Около 3 мин

Что такое страница ошибки Whitelabel? Полное техническое руководство

При создании приложений на Java — особенно с использованием Spring Boot — разработчики иногда сталкиваются с простой белой страницей с заголовком “Страница ошибки Whitelabel.”
Она часто появляется неожиданно, обычно в самый неподходящий момент, и каждый раз вызывает один и тот же вопрос: Что именно вызвало это, и как мне предотвратить это в будущем?

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

Что такое страница ошибки Whitelabel?

Страница ошибки Whitelabel — это резервная HTML-страница Spring Boot, которая появляется, когда приложение сталкивается с проблемой, но не может найти пользовательский обработчик ошибок.

Проще говоря:

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

Эта заглушка появляется как на обычных веб-маршрутах, так и на REST-эндпоинтах, если бэкенд считает, что клиент ожидает HTML.

Общие причины включают:

Отсутствие сопоставлений контроллеров
Исключения, выбрасываемые во время обработки запросов
Неправильная маршрутизация запросов
Отключенный или отсутствующий шаблонизатор
Неопределенный пользовательский обработчик /error

Хотя сама страница безвредна, она не идеальна для реальных приложений или API.

Почему появляется эта страница ошибки?

Ниже приведены наиболее частые причины:

1. Запрашиваемый URL не имеет соответствующего обработчика

Пользователь обращается к чему-то вроде:

/api/user/profile/get-more-info

но вы реализовали маршруты только под /api/user.

Spring Boot отвечает своей страницей ошибки по умолчанию.

2. Приложение выбрасывает необработанное исключение

Например:

NullPointerException
Ошибка валидации
Ошибки подключения к базе данных

Если у вас нет глобального обработчика исключений, отображается страница Whitelabel по умолчанию.

3. Запрос клиента интерпретируется как запрос браузера

REST-клиенты должны указывать:

Accept: application/json

Если этот заголовок отсутствует, Spring Boot может предположить, что клиент хочет HTML, и вернуть страницу Whitelabel вместо JSON.

4. Отсутствие или неполные веб-зависимости

Если вы случайно удалите зависимость, такую как:

<artifactId>spring-boot-starter-web</artifactId>

Автонастройка Spring может не сработать, что приведет к поведению по умолчанию.

5. Нет пользовательского контроллера ошибок или пользовательского шаблона ошибок

Spring Boot проверяет:

/error
/templates/error/
static/error/

Если ничего не найдено → страница по умолчанию.

Как удалить страницу ошибки Whitelabel

Spring Boot предлагает несколько чистых решений в зависимости от потребностей вашего приложения.

Решение 1: Полностью отключить страницу Whitelabel

Добавьте это в вашу конфигурацию:

server.error.whitelabel.enabled=false

Это остановит Spring Boot от отображения страницы по умолчанию.

Решение 2: Создайте свои собственные HTML-страницы ошибок

Для веб-приложений добавьте файлы, такие как:

src/main/resources/templates/error/404.html  
src/main/resources/templates/error/500.html

Spring Boot автоматически использует их при сопоставлении кодов состояния.

Решение 3: Реализуйте пользовательский контроллер ошибок

Идеально для бэкенд-API, желающих получать чистые JSON-ответы:

@RestController
public class CustomErrorController implements ErrorController {

    @RequestMapping("/error")
    public Map<String, Object> handleError(HttpServletResponse response) {
        Map<String, Object> data = new HashMap<>();
        data.put("status", response.getStatus());
        data.put("error", "Запрос не удался");
        return data;
    }
}

Это гарантирует, что все ошибки возвращают структурированный JSON вместо HTML.

Решение 4: Добавьте глобальную обработку исключений

Используя @RestControllerAdvice:

@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, Object>> handle(Exception ex) {
        Map<String, Object> error = new HashMap<>();
        error.put("message", ex.getMessage());
        error.put("code", 500);
        return ResponseEntity.status(500).body(error);
    }
}

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

Решение 5: Убедитесь, что маршруты фронтенда и бэкенда не пересекаются

Одностраничные приложения (React, Vue, Angular) часто обновляют страницы, которые не существуют на бэкенде. Настройка правильного резервного маршрута или правила переписывания сервера помогает избежать неожиданных ответов Whitelabel.

Лучшие практики для производства

Чтобы полностью избежать страницы по умолчанию Spring Boot, следуйте этим рекомендациям:

Всегда определяйте пользовательские страницы ошибок для приложений, ориентированных на пользователей
Стандартизируйте JSON-ответы об ошибках для API
Реализуйте глобальную обработку исключений
Проверяйте свои правила маршрутизации запросов
Убедитесь, что ваш фронтенд устанавливает правильные заголовки
Поддерживайте последовательность логирования для упрощения отладки

С этими практиками ваши пользователи — и ваши логи — никогда больше не будут загромождены неожиданными сюрпризами Whitelabel.

Часто задаваемые вопросы

Почему я получаю страницу ошибки Whitelabel при обновлении страницы в приложении React/Vue?

Потому что браузер запрашивает маршрут, который существует только на фронтенде, а не на бэкенде. Настройте резервный маршрут на фронтенде или правило переписывания сервера.

Как переключить ответы об ошибках на JSON вместо HTML?

Отключите Whitelabel, добавьте глобальный обработчик исключений и предоставьте пользовательский эндпоинт /error, возвращающий JSON.

Могу ли я полностью удалить страницу ошибки Whitelabel?

Да. Просто добавьте:

server.error.whitelabel.enabled=false

и реализуйте свой собственный контроллер ошибок или HTML-шаблон.

Почему мой API возвращает страницу Whitelabel вместо объекта ошибки?

Скорее всего, потому что запрос не содержит:

Accept: application/json

Spring Boot предполагает, что клиент хочет HTML.

Нужна ли мне отдельная страница для каждого кода ошибки?

Не обязательно, но рекомендуется для публичных сайтов. Для API обычно достаточно одной унифицированной структуры JSON.