Yol ve sorgu parametreleri nasıl çalışır?

Question

Accepted Answer

FastAPI, işlev bağımsız değişkenlerinden **yol parametrelerini** (URL yolunun bir kısmı) ve **sorgu parametrelerini** (`?` sonrası) otomatik dönüştürme ve doğrulama için tür ipuçlarını kullanarak ayıklar.

## Yol parametreleri — URL'nin bir kısmı

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

Adı yoldaki bir `{placeholder}` ile eşleşen işlev parametresi bir **yol parametresi** olur. Tür ipucu (`int`) URL'deki dizeyi otomatik olarak dönüştürür ve eşleşmezse net bir 422 hatası döndürür.

## Sorgu parametreleri — diğer her şey

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

Yolda **olmayan** işlev parametreleri **sorgu parametreleri** olur. Varsayılan değer onları isteğe bağlı hale getirir (`skip: int = 0`); `str | None = None` boş değer verilebilir isteğe bağlı bir sorgu parametresi yapar. Varsayılan olmadan zorunludur.

## Gerekli ve isteğe bağlı

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

## Her ikisini de birleştirme

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

## Neden önemli

Yol ve sorgu parametreleri, uç noktaların URL'den nasıl giriş aldığıdır — hemen hemen her API rotası için temel (kaynağı id ile alma, filtreleme, sayfalandırma, arama).

FastAPI'nin yaklaşımı zarif ve üretken olmasının kilit nedenidir: basitçe yazılı işlev parametrelerini bildirerek otomatik ayıklama, **tür dönüştürme**, **doğrulama** (kötü girdide net 422 hatalarıyla) ve zorunlu-vs-isteğe bağlı semantiğini (varsayılanlar aracılığıyla) alırsınız — hepsi standart Python tür ipuçlarından türetilmiş, manuel ayrıştırma olmadan.

Ayrımı anlamak (yol parametreleri `{placeholder}` gelir, her şey başka bir sorgu parametresidir) ve varsayılanların opsiyonelliği nasıl kontrol ettiği, FastAPI uç noktaları oluşturmak için gerekli günlük bilgidir.