Jak zaprojektować stronicowanie, filtrowanie i sortowanie dla endpointu kolekcji?

Question

IT Interview Practice · Accepted Answer

Każdy endpoint zwracający kolekcję musi **ograniczać i kształtować** wyniki. Trzy zagadnienia — stronicowanie, filtrowanie, sortowanie — wszystkie żyją w query stringu.

## Stronicowanie: offset a cursor

**Offset (oparty na stronach)** — `?page=3&limit=20` lub `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Proste i pozwala przeskoczyć na dowolną stronę, ale ma dwa problemy przy skali: `OFFSET 100000` zmusza bazę danych do przeskanowania i odrzucenia 100 tys. wierszy (wolno), a jeśli wiersze są wstawiane/usuwane między żądaniami, elementy **przesuwają się** i widzisz duplikaty lub pominięcia.

**Cursor (keyset)** — klient przekazuje nieprzezroczysty wskaźnik do ostatniego widzianego elementu.
```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 }
}
```
Serwer tłumaczy cursor na `WHERE id > 1020 ORDER BY id LIMIT 20` — wyszukiwanie po indeksie, które pozostaje szybkie na dowolnej głębokości i jest **stabilne** wobec wstawień. Kompromis: brak losowego dostępu do „strony 500".

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

## Filtrowanie i sortowanie

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filtruj** za pomocą parametrów query field=value (`status=shipped`). Utrzymuj białą listę dozwolonych pól.
- **Sortuj** parametrem `sort`; prefiks `-` oznacza malejąco (`-created_at`). Wspieraj wiele kluczy dla stabilnego uporządkowania.
- Zawsze **ograniczaj `limit`** (np. maks. 100), by klient nie mógł zażądać miliona wierszy.

## Dlaczego to ważne

To jedno z najbardziej praktycznych pytań o projektowanie API, bo niemal każdy endpoint listujący na nie trafia, a wybór ma realne konsekwencje wydajnościowe. Rozmówca zwykle drąży **kompromis offset-vs-cursor**: kandydat, który sięga po stronicowanie offsetowe wszędzie, nie odczuł bólu `OFFSET 1000000` skanującego tabelę ani buga „przesuwających się wyników", gdzie użytkownik przewijający nieskończony feed widzi ten sam post dwa razy, bo wstawiono nowy. Stronicowanie kursorem naprawia oba, zamieniając zapytanie w wyszukiwanie keyset po indeksie, dlatego każde API o dużej skali (Twitter, Stripe, Slack) używa go do feedów. Mocne odpowiedzi wspominają też o barierkach operacyjnych — białej liście pól filtrowania/sortowania (by uniknąć zapytań bez indeksu i wstrzyknięć) i ograniczaniu `limit` (by chronić bazę danych) — co odróżnia kogoś, kto uruchamiał te endpointy na produkcji, od kogoś, kto tylko o nich czytał.

Stronicowanie: offset a cursor

Filtrowanie i sortowanie

Dlaczego to ważne

Powiązane pytania