Unpoly — это библиотека для прогрессивного обновления страниц без
полной перезагрузки. Для корректной работы она накладывает определённые
требования на серверную часть приложения. Они связаны с обработкой
AJAX-запросов, корректной генерацией HTML-фрагментов и соблюдением
HTTP-стандартов.
Поддержка стандартных
HTTP-заголовков
Unpoly полагается на стандартные заголовки HTTP для определения типа
ответа. Основные требования:
- Content-Type: сервер должен правильно указывать тип
содержимого. Для обычных HTML-страниц это
text/html; charset=utf-8. Для фрагментов, которые будут
вставляться в DOM, тоже необходимо использовать HTML.
- X-Up-Target и X-Up-Fragment: при получении запроса
с этими заголовками сервер должен возвращать корректный HTML-фрагмент,
соответствующий целевому элементу.
- Cache-Control и ETag: поддержка кэширования
необязательна, но рекомендуется для повышения производительности при
повторных запросах.
Поддержка методов HTTP
Unpoly использует стандартные методы: GET и
POST. Для сложных операций возможны PUT,
PATCH и DELETE. Сервер должен корректно
обрабатывать все запросы, которые могут быть инициированы через
up.ajax(), включая:
- Проверку CSRF-токенов для защищённых POST-запросов.
- Поддержку редиректов: Unpoly корректно обрабатывает HTTP-редиректы
(
3xx) и обновляет только указанный фрагмент.
Генерация HTML-фрагментов
Unpoly ориентируется на частичное обновление страницы, поэтому сервер
обязан поддерживать отдачу отдельных HTML-фрагментов. Важные
моменты:
- Разметка должна быть валидной HTML, иначе Unpoly не
сможет корректно вставить содержимое в DOM.
- Фрагменты должны иметь уникальные id или классы,
которые совпадают с
up-target на клиенте.
- Для сложных страниц рекомендуется отдавать разные фрагменты в
зависимости от запроса: полная страница при обычном GET и только нужные
элементы при AJAX-запросе.
Обработка ошибок
Сервер должен корректно возвращать коды ошибок:
- 4xx для клиентских ошибок (например, неправильные
параметры).
- 5xx для серверных ошибок.
- Unpoly отображает содержимое ответа при ошибке в том же элементе,
куда должен был быть вставлен фрагмент, поэтому страницы ошибок можно
создавать в виде частичных шаблонов.
Форматы данных
Unpoly работает в первую очередь с HTML, но также может обрабатывать
JSON при использовании up.render(). В этом случае сервер
должен:
- Отдавать
application/json для JSON-ответов.
- В JSON включать поля
html, redirect или
focus, если необходимо управлять поведением Unpoly после
запроса.
Поддержка аутентификации и
сессий
Все стандартные механизмы аутентификации (cookies, токены, заголовки)
должны работать для AJAX-запросов. Особое внимание нужно уделять:
- CSRF-токенам, которые должны быть доступны на странице и
передаваться через заголовки.
- Проверке сессии на каждом запросе, поскольку Unpoly может отправлять
несколько частичных запросов одновременно.
Производительность и
масштабируемость
- Сервер должен быть способен быстро формировать фрагменты HTML, так
как каждый AJAX-запрос Unpoly предполагает частичное обновление
страницы.
- Использование шаблонизаторов и кэширования отдельных фрагментов
повышает отзывчивость интерфейса.
- При высокой нагрузке рекомендуется поддерживать сжатие ответов
(
gzip/brotli) для уменьшения трафика.
Логирование и отладка
Unpoly передаёт заголовки, которые полезны для логирования:
X-Up-Target — показывает, какой элемент был
обновлён.X-Up-Request — позволяет отличать обычные запросы от
запросов Unpoly.- Рекомендуется логировать эти заголовки на сервере для анализа
производительности и отладки.
Совместимость с браузерами
Все серверные ответы должны корректно обрабатываться современными
браузерами. Особое внимание стоит уделить:
- Валидности HTML, чтобы не возникали ошибки вставки фрагментов.
- Поддержке кодировок (
UTF-8), чтобы символы отображались
корректно во всех регионах.
Соблюдение этих требований обеспечивает плавное и корректное
поведение интерфейсов на Unpoly, позволяя использовать частичное
обновление страниц без потери функциональности или ошибок.