Kaip veikia kelio ir užklausos parametrai?

Question

Accepted Answer

FastAPI išgauna **kelio parametrus** (URL kelio dalis) ir **užklausos parametrus** (po `?`) iš funkcijos argumentų, naudodamas tipo užuominас automatiniam konvertavimui ir patikrinimui.

## Kelio parametrai — URL dalis

```python
@app.get("/items/{item_id}")        # {item_id} in the path
def get_item(item_id: int):          # matched by NAME; `int` converts & validates
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 error (not an int)
```

Funkcijos parametras, kurio pavadinimas atitinka `{placeholder}` kelyje, tampa **kelio parametru**. Tipo užuomina (`int`) automatiškai konvertuoja eilutę iš URL ir grąžina aiškią 422 klaidą, jei ji neatitinka.

## Užklausos parametrai — viskas kita

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # parameters NOT in the path become QUERY parameters
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

Funkcijos parametrai **ne** kelyje tampa **užklausos parametrais**. Numatytoji reikšmė juos padarо pasirinktinius (`skip: int = 0`); `str | None = None` padarо pasirinktinius pagal nulį galimus užklausos parametrus. Be numatytos reikšmės jie yra būtini.

## Būtini ir pasirinkti

```python
def search(q: str):              # REQUIRED query param (no default) → ?q=... must be present
def search(q: str = ""):          # optional, defaults to ""
def search(q: str | None = None): # optional, defaults to None
```

## Abiejų kombinavimas

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — distinguished by the path
```

## Kodėl tai svarbu

Kelio ir užklausos parametrai yra tai, kaip galiniai taškai gauna įvestis iš URL — esminė beveik kiekvienam API maršrutui (ištekliaus nuskaitymas pagal id, filtravimas, nuorodų žymėjimas, paieška).

FastAPI metodas yra elegantiškas ir pagrindinė priežastis, kodėl jis yra produktyvus: tiesiog deklaruojant užtipuotus funkcijos parametrus gausite automatinį išgavimą, **tipo konvertavimą**, **patikrinimą** (su aiškiomis 422 klaidomis dėl blogos įvesties) ir privalomo ir pasirinkto semantikos (per numatytas reikšmes) — visos iš standartinių Python tipo užuominų, be rankinio apdorojimo.

Suvokimas apie skirtumą (kelio parametrai gaunami iš `{placeholders}`, viskas kita yra užklausos parametras) ir kaip numatytos reikšmės kontroliuoja pasirinktumo yra esminės kasdienės žinios, skirtos kurti FastAPI galutiniams taškams.