Hogyan működnek az útvonal és a lekérdezési paraméterek?

Question

Accepted Answer

A FastAPI kinyeri a **útvonal paramétereket** (az URL-útvonal része) és a **lekérdezési paramétereket** (`?` után) a függvény argumentumaiból, típusjelzéseket használva az automatikus konverzióhoz és validáláshoz.

## Útvonal paraméterek — az URL része

```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)
```

Egy függvényi paraméter, amelynek neve megegyezik az útvonal `{placeholder}` elemével, **útvonal paraméter** lesz. A típusjelzés (`int`) automatikusan konvertálja az URL-ből származó karakterláncot, és egyértelmű 422-es hibát ad vissza, ha nem egyezik.

## Lekérdezési paraméterek — minden egyéb

```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}
```

Az útvonalban **nem** szereplő függvényi paraméterek **lekérdezési paraméterek** lesznek. Az alapértelmezett érték opcionálissá teszi őket (`skip: int = 0`) ; `str | None = None` nullozható opcionális lekérdezési paraméter. Alapértelmezett érték nélkül szükségesek.

## Szükséges vagy opcionális

```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
```

## Mindkettő kombinálása

```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
```

## Miért fontos ez

Az útvonal és lekérdezési paraméterek azok, ahogyan a végpontok az URL-ből kapnak bemenetet — szinte minden API útvonalhoz alapvető (erőforrás lekérése azonosító alapján, szűrés, lapozás, keresés).

A FastAPI megközelítése elegáns, és ez az oka annak, hogy produktív: egyszerűen begépelt függvényi paramétereket deklarálva automatikus kinyerést, **típuskonverziót**, **validálást** (egyértelmű 422 hibákkal a rossz bemenetre) és szükséges-vagy-opcionális szemantikát (alapértelmezett értékeken keresztül) kapsz — mindez a standard Python típusjelzésekből származik, kézi elemzés nélkül.

A különbség megértése (az útvonal paraméterek a `{placeholder}` elemekből származnak, minden egyéb egy lekérdezési paraméter) és az, hogy az alapértelmezett értékek hogyan szabályozzák az opcionalitást, alapvető napi tudás a FastAPI végpontok felépítéséhez.