+1

FastAPI: validate query parameter bằng Query() — chặn giá trị sai ngay từ cổng vào

Query parameter không validate là lỗi âm thầm của API: client gửi page=0 hoặc size=10000, server vẫn trả 200 rồi lặng lẽ trả sai dữ liệu hoặc "gánh" cả bảng. FastAPI giải quyết bằng Query() — khai báo giới hạn ngay trong chữ ký hàm, framework tự kiểm tra và trả lỗi 422 khi giá trị sai, không cần thêm một dòng if nào. Dùng cho mọi endpoint nhận phân trang, tìm kiếm hay lọc dữ liệu.

Vấn đề

Endpoint liệt kê sản phẩm có phân trang và tìm kiếm theo tên, không có Query(), thường trông thế này:

from fastapi import FastAPI

app = FastAPI()
ITEMS = [{"id": i, "name": f"san-pham-{i}"} for i in range(1, 51)]


@app.get("/items/")
def list_items(q: str | None = None, page: int = 1, size: int = 10):
    start = (page - 1) * size
    return ITEMS[start : start + size]

Thứ nhất, page=0 khiến start = -10, slice Python [-10:0] trả 10 phần tử cuối bảng — dữ liệu sai nhưng status vẫn 200, client không biết mình nhận nhầm. Thứ hai, size=10000 bắt server trả cả bảng, vừa chậm vừa tốn RAM, vài request như vậy là đủ làm API nghẽn. Thứ ba, q chỉ 1 ký tự vẫn kích hoạt tìm kiếm toàn bảng mà kết quả gần như vô nghĩa. Vá bằng if rồi raise HTTPException ở đầu mỗi endpoint thì lặp lại khắp nơi, quên một chỗ là hở một chỗ.

Giải pháp

Khai báo giới hạn ngay trong chữ ký hàm thay cho kiểm tra bằng tay:

from fastapi import FastAPI, Query

app = FastAPI()
ITEMS = [{"id": i, "name": f"san-pham-{i}"} for i in range(1, 51)]


@app.get("/items/")
def list_items(
    q: str | None = Query(default=None, min_length=2, max_length=50),
    page: int = Query(default=1, ge=1),
    size: int = Query(default=10, ge=1, le=100),
):
    results = ITEMS
    if q:
        results = [item for item in results if q in item["name"]]
    start = (page - 1) * size
    return results[start : start + size]

Giờ page nhỏ hơn 1, size vượt quá 100 hay q ngắn hơn 2 ký tự đều bị chặn trước khi hàm chạy, FastAPI trả 422 kèm thông báo rõ ràng, ví dụ Input should be greater than or equal to 1. Bốn tham số hay dùng nhất: ge/le giới hạn số, min_length/max_length giới hạn chuỗi, default đặt giá trị mặc định khi client không gửi, và pattern nếu cần khớp regex. Lưu ý: ge cho phép bằng đúng giới hạn, gt thì không — page dùng ge=1 chứ không phải gt=0, ge đọc rõ ý hơn. Có sẵn dependency phân trang dùng chung thì gắn Query() vào đó một lần, mọi endpoint hưởng luôn.

Áp dụng vào dự án của bạn

Áp dụng cho mọi endpoint nhận dữ liệu từ query string: trang danh sách, ô tìm kiếm, bộ lọc theo trạng thái hay khoảng ngày. Luôn đặt le cho size (thường là 100) để không ai "xin" cả bảng trong một request, và đặt min_length cho từ khóa tìm kiếm để tránh query vô nghĩa quét toàn bảng. Validate ở cổng vào càng chặt, code bên trong càng gọn.

Câu hỏi thường gặp

Query() khác gì Field() của Pydantic?

Cùng hệ ràng buộc ge, le, min_length — nhưng Query() dùng cho query parameter trong chữ ký hàm, Field() dùng cho trường trong model của request body.

Muốn bắt buộc client phải gửi tham số thì làm sao?

Dùng Query(...) với dấu ba chấm thay cho giá trị mặc định — thiếu tham số, FastAPI trả 422 ngay.

Lỗi 422 trả về thế nào, tùy chỉnh được không?

FastAPI trả JSON gồm mảng detail, mỗi mục ghi rõ vị trí lỗi (loc), thông báo (msg) và loại lỗi (type). Muốn đổi định dạng chung cho toàn API, đăng ký exception handler cho RequestValidationError một lần ở app.


Bài đầy đủ bản tiếng Anh (có thêm phần FAQ và nguồn tham khảo): https://linhfish.dev/en/2026/11/20/fastapi-validate-query-parameters-with-query-reject-bad-values-at-the-gate/


All Rights Reserved

Viblo
Let's register a Viblo Account to get more interesting posts.