Bagaimanakah parameter laluan dan parameter pertanyaan berfungsi?

Question

Accepted Answer

FastAPI mengekstrak **parameter laluan** (bahagian laluan URL) dan **parameter pertanyaan** (selepas `?`) daripada argumen fungsi, menggunakan petunjuk jenis untuk penukaran dan pengesahan automatik.

## Parameter laluan — bahagian 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 fungsi yang namanya sepadan dengan `{placeholder}` dalam laluan menjadi **parameter laluan**. Petunjuk jenis (`int`) secara otomatis menukar rentetan daripada URL dan mengembalikan ralat 422 yang jelas jika ia tidak sepadan.

## Parameter pertanyaan — segala-galanya yang lain

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

Parameter fungsi **tidak** dalam laluan menjadi **parameter pertanyaan**. Nilai lalai menjadikannya pilihan (`skip: int = 0`); `str | None = None` menjadikan parameter pertanyaan pilihan yang boleh nol. Tanpa nilai lalai, ia diperlukan.

## Diperlukan vs pilihan

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

## Menggabungkan kedua-duanya

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

## Mengapa ini penting

Parameter laluan dan pertanyaan adalah cara titik akhir menerima input daripada URL — asas untuk hampir setiap laluan API (mengambil sumber daya mengikut id, penapis, pensejajaran halaman, pencarian).

Pendekatan FastAPI adalah elegan dan alasan kunci mengapa ia produktif: hanya dengan mengisytiharkan parameter fungsi yang ditaip memberikan anda ekstraksi automatik, **penukaran jenis**, **pengesahan** (dengan ralat 422 yang jelas pada input yang buruk), dan semantik wajib-berbanding-pilihan (melalui nilai lalai) — semuanya berasal daripada petunjuk jenis Python standard, tanpa penghuraian manual.

Memahami perbezaan (parameter laluan datang daripada `{placeholders}`, segala-galanya yang lain ialah parameter pertanyaan) dan bagaimana nilai lalai mengawal kebolehpilihan adalah pengetahuan harian yang penting untuk membina titik akhir FastAPI.