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

Как сделать пагинацию, фильтрацию и сортировку?

На этой странице
Кратко

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

Вопрос

Как сделать в Express API пагинацию, фильтрацию и сортировку? Чем страничная пагинация отличается от курсорной?

Пример адреса

GET /api/users?page=2&limit=20&search=anna&sort=createdAt&order=desc

Проверка параметров

import { z } from "zod";
 
const listUsersQuerySchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  search: z.string().trim().max(100).optional(),
  sort: z.enum(["name", "createdAt"]).default("createdAt"),
  order: z.enum(["asc", "desc"]).default("desc"),
});
 
const query = listUsersQuerySchema.parse(request.query);
const offset = (query.page - 1) * query.limit;

Максимальный limit защищает сервер и базу от запроса на миллионы строк.

Формат ответа

{
  "data": [],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 53,
    "pages": 3
  }
}

Почему сортировка требует белого списка

Значение имени столбца нельзя безопасно передать обычным параметром SQL $1. Поэтому клиент выбирает только из заранее разрешённых вариантов.

const sortColumns = {
  name: users.name,
  createdAt: users.createdAt,
} as const;
 
const sortColumn = sortColumns[query.sort];

Не вставляй request.query.sort прямо в строку SQL.

Страничная и курсорная пагинация

Страница и смещение

?page=3&limit=20

Понятна пользователю, но большое смещение может работать медленно, а изменения между запросами сдвигают результаты.

Курсор

?afterId=120&limit=20

Удобен для бесконечной ленты и больших таблиц. Следующая страница начинается после известной записи.

Для небольшого служебного API можно начать со страниц и перейти к курсору при необходимости.

Что важно помнить

  • Любой список ограничивается максимальным limit, даже если клиент его не передал.
  • Поле сортировки выбирается только из белого списка — имя столбца нельзя подставить параметром SQL.
  • Ответ со списком полезно дополнять метаданными: page, limit, total.
  • OFFSET замедляется на дальних страницах и пропускает строки при вставках; курсор устойчивее.

Мини-шпаргалка

  • Любой список должен иметь ограничение.
  • page и limit проверяются и преобразуются в числа.
  • Поле сортировки выбирается только из белого списка.
  • Ответу полезны сведения о пагинации.
  • Курсор устойчивее на больших изменяемых списках.

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

Zod: Basics, Zod: API, node-postgres: Queries.

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

Поиск

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