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
():
{: item_id}
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.
():
{: item_id}
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.
@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.
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
@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
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.