Kaip suprojektuoti puslapiavimą, filtravimą ir rikiavimą kolekcijos endpoint?

Question

IT Interview Practice · Accepted Answer

Bet kuris endpoint, grąžinantis kolekciją, turi **apriboti ir suformuoti** rezultatus. Trys rūpesčiai — puslapiavimas, filtravimas, rikiavimas — visi gyvena query string.

## Puslapiavimas: offset vs cursor

**Offset (pagal puslapį)** — `?page=3&limit=20` arba `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Paprasta ir leidžia peršokti į bet kurį puslapį, bet dideliu masteliu turi dvi problemas: `OFFSET 100000` priverčia duomenų bazę nuskaityti ir atmesti 100k eilučių (lėta), o jei tarp užklausų įterpiamos/trinamos eilutės, elementai **pasislenka**, ir matai dublikatus ar praleidimus.

**Cursor (keyset)** — klientas perduoda neskaidrią (opaque) rodyklę į paskutinį matytą elementą.
```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 }
}
```
Serveris verčia cursor į `WHERE id > 1020 ORDER BY id LIMIT 20` — indeksuotą paiešką, kuri lieka greita bet kokiame gylyje ir yra **stabili** įterpimų atžvilgiu. Kompromisas: nėra atsitiktinės prieigos prie „500 puslapio“.

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

## Filtravimas ir rikiavimas

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filtruok** su field=value query params (`status=shipped`). Įtrauk leidžiamus laukus į whitelist.
- **Rikiuok** su `sort` param; `-` priešdėlis reiškia mažėjančiai (`-created_at`). Palaikyk kelis raktus stabiliai tvarkai.
- Visada **apribok `limit`** (pvz. maks. 100), kad klientas negalėtų prašyti milijono eilučių.

## Kodėl tai svarbu

Tai vienas praktiškiausių API projektavimo klausimų, nes beveik kiekvienas sąrašo endpoint su tuo susiduria, ir pasirinkimas turi realių našumo pasekmių. Interviuotojas paprastai gilinasi į **offset-vs-cursor kompromisą**: kandidatas, visur griebiantis offset puslapiavimo, nejuto `OFFSET 1000000` skenuojančio lentelę skausmo, ar „slenkančių rezultatų“ klaidos, kai naudotojas, slenkantis begalinį feed, mato tą patį įrašą du kartus, nes buvo įterptas naujas. Cursor puslapiavimas ištaiso abu paversdamas užklausą indeksuota keyset paieška, todėl kiekviena didelio mastelio API (Twitter, Stripe, Slack) naudoja jį feeds. Stiprūs atsakymai taip pat pamini operacinius apsauginius: filtravimo/rikiavimo laukų whitelist (kad išvengtų neindeksuotų užklausų ir injekcijos) ir `limit` ribojimą (kad apsaugotų duomenų bazę) — tai atskiria žmogų, valdžiusį šiuos endpoints production, nuo to, kuris tik apie juos skaitė.

Puslapiavimas: offset vs cursor

Filtravimas ir rikiavimas

Kodėl tai svarbu

Susiję klausimai