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

Question

IT Interview Practice · Accepted Answer

Любой endpoint, возвращающий коллекцию, должен ограничивать и формировать результаты. Три заботы — пагинация, фильтрация, сортировка — все живут в query string.

Пагинация: offset vs cursor

Offset (постраничная) — ?page=3&limit=20 или ?offset=40&limit=20.

## Пагинация: offset vs cursor

**Offset (постраничная)** — `?page=3&limit=20` или `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Проста и позволяет перепрыгнуть на любую страницу, но имеет две проблемы на масштабе: `OFFSET 100000` заставляет базу сканировать и отбросить 100k строк (медленно), и если строки вставляются/удаляются между запросами, элементы **смещаются**, и вы видите дубликаты или пропуски.

**Cursor (keyset)** — клиент передаёт непрозрачный указатель на последний увиденный элемент.
```http
GET /orders?limit=20&cursor=eyJpZCI6MTAyMH0 HTTP/1.1
```
```http
HTTP/1.1 200 OK

{
  "data": [ /* 20 orders */ ],
  "page": { "next_cursor": "eyJpZCI6MTA0MH0", "has_more": true }
}
```
Сервер переводит cursor в `WHERE id > 1020 ORDER BY id LIMIT 20` — индексированный поиск, остающийся быстрым на любой глубине и **стабильный** к вставкам. Компромисс: нет случайного доступа к «странице 500».

```text
Offset  → small datasets, admin UIs, "jump to page N"
Cursor  → large/infinite feeds, real-time data, mobile scroll
```

## Фильтрация и сортировка

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Фильтруйте** query-параметрами field=value (`status=shipped`). Ведите whitelist разрешённых полей.
- **Сортируйте** параметром `sort`; префикс `-` означает по убыванию (`-created_at`). Поддерживайте несколько ключей для стабильного порядка.
- Всегда **ограничивайте `limit`** (например, максимум 100), чтобы клиент не мог запросить миллион строк.

## Почему это важно

Это один из самых практичных вопросов проектирования API, потому что почти каждый endpoint со списком с ним сталкивается, а выбор имеет реальные последствия для производительности. Интервьюер обычно зондирует **компромисс offset-vs-cursor**: кандидат, который повсюду тянется к offset-пагинации, не прочувствовал боль `OFFSET 1000000`, сканирующего таблицу, или баг «смещающихся результатов», когда пользователь, прокручивая бесконечную ленту, видит один и тот же пост дважды, потому что был вставлен новый. Cursor-пагинация исправляет и то, и другое, превращая запрос в индексированный keyset-поиск, поэтому каждый крупномасштабный API (Twitter, Stripe, Slack) использует её для лент. Сильные ответы также упоминают операционные ограждения — whitelist полей фильтрации/сортировки (чтобы избежать неиндексированных запросов и инъекций) и ограничение `limit` (для защиты базы) — что отделяет того, кто эксплуатировал эти endpoint'ы в production, от того, кто только читал о них.

Пагинация: offset vs cursor

Фильтрация и сортировка

Почему это важно

Похожие вопросы