re:re:actable
Урок 042 минуты чтения

Как проектировать 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=asc

Whitelist сортируемых полей обязателен:

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.

Документация

Microsoft: Filter and paginate data, MDN: URLSearchParams.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам