Кастомные страницы ошибок

Как кастомизировать стандартные страницы ошибок

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

Для упрощения процесса, я создал небольшую утилиту (прямая ссылка на проект в GitHub), по сути Node.js скрипт, которая позволяет создавать статические страницы ошибок в собственном дизайне и со своими текстовыми сообщениями. По умолчанию, утилита содержит только один шаблон в минималистичном дизайне (с поддержкой доступности и адаптивности, на сколько это возможно в такой простой странице). Но если вас не устраивает такой дизайн, то вы можете с легкостью изменить его, путем создания собственного: со своими стилями, шрифтами, изображениями и текстами.

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

Для упрощения интеграции, утилита автоматически создает сниппет с конфигурацией веб сервера, который легко может быть добавлен в конфигурацию вашего веб сервера. На текущий момент сниппет создается только для Nginx. Другие виды серверов будут добавлены позже (в качестве альтернативы, вы можете создать Pull Request с таким улучшениями, либо оформить Feature Request).

Использование

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

$ git clone git@github.com:sapachev/error-pages.git
…
$ npm install --production
…
$ npm run build
…
INFO: Start building process
INFO: Flush build directory '/home/error-pages/dist'
INFO: Compile pages from source data:
 • /home/error-pages/dist/400.html
 • /home/error-pages/dist/401.html
 • /home/error-pages/dist/403.html
 • /home/error-pages/dist/404.html
 • /home/error-pages/dist/410.html
 • /home/error-pages/dist/500.html
 • /home/error-pages/dist/502.html
 • /home/error-pages/dist/503.html
 • /home/error-pages/dist/504.html
INFO: Compile web servers config snippets from source data:
 • /home/error-pages/dist/nginx-error-pages.conf
INFO: Build Tailwind CSS styles
INFO: Run 'INPUT="/home/error-pages/themes/minimalistic/@assets/css/main.twnd.css" OUTPUT="/home/error-pages/dist/@assets/css/main.css" npm run build:tailwind' command
INFO: Tailwind CSS styles were built
INFO: Copying assets to '/home/error-pages/dist/@assets' directory
INFO: Building process was completed in 1.727s

Продвинутое использование

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

Основная конфигурация утилиты хранится в файле config.json в корневой папке, которую можно менять в соответствии со своими требованиями:

{
  "tailwind": true,
  "theme": "minimalistic",
  "locale": "en"
}

Шаблоны

Все шаблоны хранятся в папке themes, где стандартной темой является minimalistic, которую можно изменить или добавить новую. Каких‑то особых требований к шаблонам страниц нет: каждый шаблон является обыкновенным HTML документом, с внедренными переменными, на месте которых будут текстовки из файлов локализации. Для обработки внедренных переменных используется библиотека mustache.js. Таким образом, если нужно реализовать какую‑то особенную логику в своих шаблонах, то вы можете ознакомиться с документацией этой библиотеки для определения имеющихся возможностей шаблонизации.

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

Стили

Стилизация шаблонов базируется на фреймворке Tailwind CSS. С помощью этого фреймворка, можно быстро описывать стили страниц без необходимости писать отдельный CSS код. Точкой входа для стилей Tailwind должен быть файл themes/<name>/@assets/css/main.twnd.css. Из него в дальнейшем будет создан файл main.css, который содержит скомпилированные и минифицированные стили. В дополнение, можно настроить Tailwind с помощью создания кастомной конфигурации, расположенной в файле theme.tailwind.config.js в корне папки с темой, и описать в ней любые опции Tailwind. Полный список опций Tailwind доступен в документации самого Tailwind.

Однако, если по каким-то причинам использование Tailwind не требуется (например, стили уже описаны ранее в CSS), компиляцию стилей Tailwind можно отключить в основной конфигурации утилиты (файл config.json). В этом случае шаг сборки стилей будет просто пропущен без какого-либо влияния на финальный результат.

Текстовые сообщения и Локализация

Все текстовые сообщения хранятся в JSON файлах, разделенных по признаку языка, и расположены в папке src. Каждая страница создается из соответствующего ей файла локализации вида <Код HTTP>.json (<Код HTTP> – это число, соответствующее коду ошибки HTTP). Таким образом, если нужно создать страницу для кода, который еще не описан, то просто создайте соответствующий JSON файл, содержащий описание этого статуса в соответствующих свойствах.

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

Для локализации страниц, просто создайте новую папку в директории src, содержащую JSON файлы с текстами страниц. Создавая JSON файлы, вы можете описать любой набор HTTP кодов (например, только для 400-ых ошибок) – просто следуйте конвенции именования, и не забывайте выделять общие тексты в файл common.json.

Конфигурации сервера

В процессе работы, Утилита автоматически создаст сниппет для вашего сервера, который будет содержать лишь те страницы, которые были созданы. Данный сниппет будет содержать настройки обрабатываемых ошибок, и указывать на страницы, которые будут их представлять. Как было сказано ранее, на данный момент только Nginx поддерживается.

Для использования полученных страниц, остается только скопировать на сервер все файлы из папки dist и включить использование сниппета в уже существующей конфигурации сервера. В соответствии с шаблоном сниппета, все страницы должны быть расположены в папке /usr/share/nginx/html/error-pages. В случае если настройки в снипетта не подходят, то вы можете отредактировать шаблон сниппета в папке snippets. Так же как и для тем оформления, шаблоны конфигураций поддерживают mustache.js, тем позволяя реализовать в шаблоне любую логику (списки, условия и т. д.).

Сам по себе конфиг, я рекомендую располагать в папке /etc/nginx/snippets/, а для его подключения использовать строчку конфигурации: include /etc/nginx/snippets/nginx-error-pages.conf;. Разумеется, это не более чем рекомендация, т.к. в реальности всё может быть иначе или сложнее.

Ниже приведен простой пример конфигурации веб‑сервера с включенным в нее сниппетом кастомных ошибок:

server {
    server_name example.com;
    access_log /var/log/nginx/example.access.log;

    include /etc/nginx/snippets/nginx-error-pages.conf;

    location / {
        root /data/www;
    }
}

Демо

Посмотреть как выглядят страницы ошибок можно на моем сайте по следующим ссылкам:

• 400 Bad Request

• 401 Unauthorized

• 403 Forbidden

• 404 Not Found

• 410 Gone

• 500 Internal Server Error

• 502 Bad Gateway

• 503 Service Unavailable

• 504 Gateway Timeout

Сообщение об ошибках и запрос новых функций

Код утилиты нельзя назвать каким‑то сложным, однако, несмотря на этот факт, все значимые части покрыты юнит‑тестами. Впрочем, это не является гарантией отсутствия каких‑либо ошибок, поэтому если вы столкнетесь с какими‑то проблемами, то, пожалуйста, сообщите мне о них, через создание Issue в репозитории проекта: https://github.com/sapachev/error‑pages/issues

Также приветствуется создание запросов новых функций, которые вы хотели бы увидеть в данной утилите.

Участие в разработке

Проект открыт для всех желающих, и если у вас есть идеи, а главное желание и возможности их реализовать, то с радостью рассмотрю их в виде Pull Request. Со своей стороны готов предоставить вам поддержку в реализации вашей задумки. Не стесняйтесь спрашивать меня о коде, и возможных решениях вашей идеи.

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

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

Как объявлено в заголовке статьи, кастомизированы был следующие ошибки:

1. 403 — Ошибка авторизации, доступ запрещён.
2. 404 — Страница не найдена;
3. 500 — Внутренняя ошибка сервера;

Кастомизация ошибок 404, 500

Для кастомизации ошибок 404 и 500 необходимо написать обработчики запросов, и достаточно написать их представления в виде метода.

В шаблоны добавляем свои кастомизированные html файлы, то есть:

• error404.html
• error500.html

Модуль, в котором реализованы представления для данного сайта — это

home.

В шаблонах этого же модуля помещены сами шаблоны кастомизированных ошибок.

В файле

urls.py

главного модуля сайта переопределяем обработчики по умолчанию:

• handler404
• handler500

В коде это выглядит так:

from home.views import e_handler404, e_handler500

handler404 = e_handler404
handler500 = e_handler500


  Опишем представления в файле

  

   views.py

  

  модуля

  

   home:

  
from django.shortcuts import render_to_response
from django.template import RequestContext


def e_handler404(request):
    context = RequestContext(request)
    response = render_to_response('error404.html', context)
    response.status_code = 404
    return response


def e_handler500(request):
    context = RequestContext(request)
    response = render_to_response('error500.html', context)
    response.status_code = 500
    return response


  Кастомизация ошибки 403

 

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

  В Django это достигается за счёт проверки статуса пользователя и добавления на страницы защитного токена, механизм

  

   CSRF.

  

  Данная ошибка может возникнуть и в том случае, если пользователь авторизован, но совершает действия, при которых требуется проверка токена CSRF, а сам токен был потерян или не верен. Дело в том, что для корректности работы токена, необходимо добавлять в шаблоне в формах специальный тег:
 
{% csrf_token %}


  В него и будет подставляться токен, но просто добавить в шаблон, его не достаточно. Прежде, чем начать рендер шаблон, необходимо добавить токен в контекст, который будет передан в шаблон. То есть,
 
from django.template.context_processors import csrf
from django.shortcuts import render_to_response


def any_request(request):
    context = {}
    context.update(csrf(request))

    ...
    return render_to_response('any_request.html', context=context)


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

  

   settings.py

  

  добавлен модуль csrf и указано представление, которое будет заниматься обработкой данной ошибки:
 
MIDDLEWARE = [
    ...
    'django.middleware.csrf.CsrfViewMiddleware',
    ...
]

CSRF_FAILURE_VIEW = 'home.views.csrf_failure'


  В шаблонах добавим

  

   error403.html,

  

  а в файле

  

   views.py

  

  пропишем обработчик представления.
 
def csrf_failure(request, reason=""):
    context = RequestContext(request)
    response = render_to_response('error403.html', context)
    response.status_code = 403
    return response


  Для

  

   Django

  

  рекомендую
   VDS-сервера хостера Timeweb
  .
 

Узнайте, как настроить кастомные 404 и 500 страницы на вашем сайте для улучшения пользовательского опыта и профессионализма!

Кастомные 404 и 500 страницы являются важными элементами любого сайта, так как они помогают пользователю понять, что что-то пошло не так, и предлагают дальнейшие действия для решения проблемы. В этой статье мы рассмотрим, как настроить кастомные 404 и 500 страницы на сайте.

Что такое 404 и 500 ошибки

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

Настройка кастомной 404 страницы

Для настройки кастомной 404 страницы выполните следующие шаги:

1. Создайте новый HTML-файл с именем 404.html.
2. Добавьте в этот файл HTML-содержимое, которое вы хотите отображать на кастомной странице 404.
3. Загрузите файл 404.html на ваш сервер в корневую директорию сайта.

Теперь, когда пользователи попадут на несуществующую страницу, они увидят вашу кастомную 404 страницу.

😉 Пример содержимого файла 404.html:

<!DOCTYPE html>
<html>
<head>
  <title>404 - Страница не найдена</title>
</head>
<body>
  <h1>Ошибка 404</h1>
  <p>К сожалению, запрашиваемая вами страница не найдена. Возможно, она была удалена или перемещена.</p>
  <a href="/">Вернуться на главную страницу</a>
</body>
</html>

Настройка кастомной 500 страницы

Настройка кастомной 500 страницы аналогична настройке 404 страницы:

1. Создайте новый HTML-файл с именем 500.html.
2. Добавьте в этот файл HTML-содержимое, которое вы хотите отображать на кастомной странице 500.
3. Загрузите файл 500.html на ваш сервер в корневую директорию сайта.

Теперь, когда сервер столкнется с внутренней ошибкой, пользователи увидят вашу кастомную 500 страницу.

😉 Пример содержимого файла 500.html:

<!DOCTYPE html>
<html>
<head>
  <title>500 - Внутренняя ошибка сервера</title>
</head>
<body>
  <h1>Ошибка 500</h1>
  <p>Извините, на сервере произошла внутренняя ошибка. Мы работаем над ее устранением.</p>
  <a href="/">Вернуться на главную страницу</a>
</body>
</html>

Теперь вы знаете, как настроить кастомные 404 и 500 страницы на вашем сайте. Это поможет улучшить пользовательский опыт и сделать ваш сайт более профессиональным. Удачи в веб-разработке!