Как сделать пагинацию, фильтрацию и сортировку?
На этой странице
Списочный маршрут должен ограничивать количество строк. Параметры страницы, фильтра и сортировки нужно проверить и превратить в безопасный запрос к базе.
Вопрос
Как сделать в 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проверяются и преобразуются в числа.- Поле сортировки выбирается только из белого списка.
- Ответу полезны сведения о пагинации.
- Курсор устойчивее на больших изменяемых списках.