Path parameter và query parameter hoạt động như thế nào?

Question

Accepted Answer

FastAPI trích xuất **path parameter** (phần thuộc đường dẫn URL) và **query parameter** (phần sau dấu `?`) từ các tham số của function, dùng type hints để chuyển đổi và validate chúng tự động.

## Path parameter — phần thuộc URL

```python
@app.get("/items/{item_id}")        # {item_id} trong path
def get_item(item_id: int):          # khớp theo TÊN; `int` chuyển đổi & validate
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → lỗi 422 (không phải int)
```

Một tham số của function có tên khớp với một `{placeholder}` trong path sẽ trở thành **path parameter**. Type hint (`int`) tự động chuyển đổi chuỗi từ URL và trả về lỗi 422 rõ ràng nếu nó không khớp.

## Query parameter — mọi thứ còn lại

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # các tham số KHÔNG có trong path trở thành QUERY parameter
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

Các tham số của function **không** nằm trong path trở thành **query parameter**. Một giá trị mặc định khiến chúng tùy chọn (`skip: int = 0`); `str | None = None` tạo ra một query param tùy chọn cho phép null. Không có giá trị mặc định, chúng là bắt buộc.

## Bắt buộc so với tùy chọn

```python
def search(q: str):              # query param BẮT BUỘC (không mặc định) → ?q=... phải có
def search(q: str = ""):          # tùy chọn, mặc định là ""
def search(q: str | None = None): # tùy chọn, mặc định là None
```

## Kết hợp cả hai

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — phân biệt qua path
```

## Tại sao điều này quan trọng

Path và query parameter là cách các endpoint nhận input từ URL — cơ bản với gần như mọi route API (lấy một resource theo id, lọc, phân trang, tìm kiếm).

Cách tiếp cận của FastAPI thanh lịch và là lý do then chốt khiến nó năng suất: chỉ cần khai báo các tham số function có kiểu, bạn nhận được trích xuất tự động, **chuyển đổi kiểu**, **validation** (với lỗi 422 rõ ràng khi input sai), và ngữ nghĩa bắt-buộc-so-với-tùy-chọn (qua giá trị mặc định) — tất cả được suy ra từ type hints Python chuẩn, không cần parse thủ công.

Hiểu sự phân biệt (path param đến từ `{placeholder}`, mọi thứ khác là query param) và cách giá trị mặc định kiểm soát tính tùy chọn là kiến thức thiết yếu hằng ngày để xây dựng endpoint FastAPI.