Skip to content

От переводчика

Это машинный перевод (DeepSeek) статьи https://fastapi.tiangolo.com/tutorial/query-param-models/

Версия от 03.09.2026

Неочевидных моментов в уроке не обнаружено, но я рад сообщить, что дополнил базу инструмента для импорта модулей и классов в python классами, использующимися в уроке.

Подпишитесь на канал "Изучаем FastAPI", чтобы ссылки на инструмент работала.

 

Перевод прочих разделов документации буду по мере сил делать.

Обо мне

Модели параметров запроса

Если у вас есть группа связанных параметров запроса, вы можете создать модель Pydantic, чтобы объявить их.

Это позволит вам повторно использовать модель в нескольких местах, а также объявлять валидации и метаданные для всех параметров сразу. 😎

Примечание

Это поддерживается начиная с версии FastAPI 0.115.0. 🤓

Параметры запроса с моделью Pydantic

Объявите параметры запроса, которые вам нужны, в модели Pydantic, а затем объявите параметр как Query:

from typing import Annotated, Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с Annotated.

from typing import Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: FilterParams = Query()):
    return filter_query

FastAPI извлечёт данные для каждого поля из параметров запроса в запросе и передаст вам определённую вами модель Pydantic.

Проверьте документацию

Вы можете увидеть параметры запроса в интерфейсе документации по адресу /docs:

Запрет дополнительных параметров запроса

В некоторых особых случаях использования (вероятно, не очень распространённых) вы можете захотеть ограничить параметры запроса, которые вы хотите получать.

Вы можете использовать конфигурацию модели Pydantic, чтобы forbid (запретить) любые extra (дополнительные) поля:

from typing import Annotated, Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    model_config = {"extra": "forbid"}

    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с Annotated.

from typing import Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    model_config = {"extra": "forbid"}

    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: FilterParams = Query()):
    return filter_query

Если клиент попытается отправить какие-либо дополнительные данные в параметрах запроса, он получит ответ с ошибкой.

Например, если клиент попытается отправить параметр запроса tool со значением plumbus, например:

https://example.com/items/?limit=10&tool=plumbus

Он получит ответ с ошибкой, сообщающий, что параметр запроса tool не разрешён:

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["query", "tool"],
            "msg": "Extra inputs are not permitted",
            "input": "plumbus"
        }
    ]
}

Итог

Вы можете использовать модели Pydantic для объявления параметров запроса в FastAPI. 😎

Совет

Спойлер: вы также можете использовать модели Pydantic для объявления cookie и заголовков, но об этом вы прочитаете позже в руководстве. 🤫