Vigezo vya njia na vigezo vya query vina kazi gani?

Question

Accepted Answer

FastAPI hutoa **vigezo vya njia** (sehemu ya njia ya URL) na **vigezo vya query** (baada ya `?`) kutoka kwa hoja za kazi, kwa kutumia vidokezo vya aina kwa ajili ya uonezaji na uthibitisho otomati.

## Vigezo vya njia — sehemu ya URL

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

Parameter ya kazi ambayo jina lake linapatana na `{placeholder}` katika njia inakuwa **parameter ya njia**. Kidokezo cha aina (`int`) kinabadilisha kiotomatia kamba kutoka URL na kurudisha hitilafu 422 wazi ikiwa haipatani.

## Vigezo vya query — kila kitu kingine

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

Migezo ya kazi **si** katika njia huwa **vigezo vya query**. Thamani ya kawaida inayafanya kuwa hiari (`skip: int = 0`); `str | None = None` inafanya parameter ya query hiari na inayoweza kuwa null. Bila thamani ya kawaida, ni lazima.

## Inayohitajika kwa inayokosekana

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

## Kuchanganya zote mbili

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

## Kwa nini inamaanisha

Vigezo vya njia na query ni jinsi mwisho wa njia unavyokubali pembejeo kutoka kwa URL — msingi wa karibu kila njia ya API (kupata rasilimali kwa id, kuchemsha kwa kichwa, kusambaza vipande, kutafuta).

Mwonekano wa FastAPI ni maalum na sababu kuu inayofanya kuwa na uzalishaji: kwa kukamatia vigezo vya kazi vilivyosambazwa maelezo, unakuwa na kutoa otomati, **ubadilishaji wa aina**, **uthibitisho** (na hitilafu 422 wazi kwa pembejeo mbaya) na semantiki ya inayohitajika-kwa-inayokosekana (kupitia makadrisha) — yote inayotokana na kidokezo cha aina cha Python cha kawaida, bila uchambuzi wa nodhi.

Kuelewa tofauti (vigezo vya njia vinatoka kwa `{placeholder}`, kila kitu kingine ni parameter ya query) na jinsi makadrisha yanayodhibiti kuwa hiari ni ujuzi wa kila siku wa msingi kwa ajili ya kujenga mwisho wa njia wa FastAPI.