Как проектировать pagination, filtering и sorting?
На этой странице
Списочные REST endpoints почти всегда должны поддерживать pagination, filtering и sorting. Это защищает базу от огромных выборок и дает frontend предсказуемый контракт для таблиц, каталогов и админок.
Вопрос
Как проектировать пагинацию, фильтрацию и сортировку списков? Чем offset-пагинация отличается от cursor-пагинации?
Offset pagination
GET /api/products?page=2&limit=20Ответ:
{
"items": [],
"meta": {
"page": 2,
"limit": 20,
"total": 135
}
}Плюсы: просто реализовать. Минусы: на больших таблицах может быть медленно, а при изменении данных между запросами возможны дубли или пропуски.
Cursor pagination
GET /api/products?cursor=prd_100&limit=20Ответ:
{
"items": [],
"nextCursor": "prd_120"
}Cursor pagination лучше для бесконечной ленты и больших данных.
Filtering
GET /api/products?categoryId=10&minPrice=100&inStock=trueФильтры должны быть явно поддержаны API. Не стоит позволять клиенту передавать произвольный SQL-like filter без контроля.
Sorting
GET /api/products?sortBy=price&sortOrder=ascWhitelist сортируемых полей обязателен:
const allowedSortFields = ['createdAt', 'price', 'title'];Иначе можно получить ошибки, утечки внутренних полей или дорогие запросы без индексов.
Что важно помнить
- Сервер должен ограничивать максимальный
limit(например, 100), иначе клиент может запросить миллион записей. - Подсчет
totalна больших таблицах дорогой; для бесконечной ленты часто достаточноhasNextPage. - Сортировка должна быть детерминированной: добавляйте уникальное поле (
id) вторым ключом, иначе записи «прыгают» между страницами. - Параметры фильтров на frontend удобно хранить в URL (
useSearchParams), чтобы ссылкой можно было поделиться.
Мини-шпаргалка
- Списки должны иметь
limit. - Offset pagination проста, cursor pagination лучше для больших потоков.
- Filters должны быть whitelisted.
- Sorting fields должны быть whitelisted.
- Response должен возвращать
itemsи metadata.