Skip to content

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

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

Версия от 03.09.2026

По этой теме хочу также рекомендовать свой разбор неочевидных моментов.

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

 

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

Обо мне

Параметры запроса

Когда вы объявляете другие параметры функции, которые не являются частью параметров пути, они автоматически интерпретируются как параметры «запроса» (query parameters).

from fastapi import FastAPI

app = FastAPI()

fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

Запрос (query) — это набор пар «ключ-значение», которые идут после символа ? в URL и разделяются символами &.

Например, в URL:

http://127.0.0.1:8000/items/?skip=0&limit=10

...параметрами запроса являются:

  • skip: со значением 0
  • limit: со значением 10

Поскольку они являются частью URL, они «естественным образом» представляют собой строки.

Но когда вы объявляете их с типами Python (в примере выше — как int), они преобразуются в этот тип и валидируются на соответствие ему.

Все те же процессы, которые применяются к параметрам пути, применяются и к параметрам запроса:

  • Поддержка в редакторе (очевидно)
  • «Разбор» данных
  • Валидация данных
  • Автоматическая документация

Значения по умолчанию

Поскольку параметры запроса не являются фиксированной частью пути, они могут быть необязательными и иметь значения по умолчанию.

В примере выше у них есть значения по умолчанию skip=0 и limit=10.

Таким образом, переход по URL:

http://127.0.0.1:8000/items/

будет эквивалентен переходу по:

http://127.0.0.1:8000/items/?skip=0&limit=10

Но если вы перейдёте, например, по:

http://127.0.0.1:8000/items/?skip=20

Значения параметров в вашей функции будут:

  • skip=20: потому что вы задали его в URL
  • limit=10: потому что это было значение по умолчанию

Необязательные параметры

Таким же образом вы можете объявлять необязательные параметры запроса, установив их значение по умолчанию в None:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

В этом случае параметр функции q будет необязательным и по умолчанию будет равен None.

Совет

Также обратите внимание, что FastAPI достаточно умён, чтобы определить, что параметр пути item_id является параметром пути, а q — нет, поэтому q является параметром запроса.

Преобразование типов параметров запроса

Вы также можете объявлять типы bool, и они будут преобразованы:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None, short: bool = False):
    item = {"item_id": item_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

В этом случае, если вы перейдёте по:

http://127.0.0.1:8000/items/foo?short=1

или

http://127.0.0.1:8000/items/foo?short=True

или

http://127.0.0.1:8000/items/foo?short=true

или

http://127.0.0.1:8000/items/foo?short=on

или

http://127.0.0.1:8000/items/foo?short=yes

или при любой другой вариации регистра (верхний регистр, первая буква заглавная и т. д.), ваша функция увидит параметр short со значением bool, равным True. В противном случае — False.

Несколько параметров пути и запроса

Вы можете объявлять несколько параметров пути и параметров запроса одновременно, FastAPI знает, что есть что.

И вам не нужно объявлять их в каком-либо определённом порядке.

Они будут обнаружены по имени:

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int, item_id: str, q: str | None = None, short: bool = False
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

Обязательные параметры запроса

Когда вы объявляете значение по умолчанию для непутевых параметров (пока мы видели только параметры запроса), то он не является обязательным.

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

Но когда вы хотите сделать параметр запроса обязательным, вы можете просто не объявлять никакого значения по умолчанию:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(item_id: str, needy: str):
    item = {"item_id": item_id, "needy": needy}
    return item

Здесь параметр запроса needy является обязательным параметром запроса типа str.

Если вы откроете в браузере URL вида:

http://127.0.0.1:8000/items/foo-item

...не добавив обязательный параметр needy, вы увидите ошибку вида:

{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "query",
        "needy"
      ],
      "msg": "Field required",
      "input": null
    }
  ]
}

Поскольку needy является обязательным параметром, вам нужно указать его в URL:

http://127.0.0.1:8000/items/foo-item?needy=sooooneedy

...это сработает:

{
    "item_id": "foo-item",
    "needy": "sooooneedy"
}

И конечно, вы можете определить некоторые параметры как обязательные, некоторые — как имеющие значение по умолчанию, а некоторые — как полностью необязательные:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str, needy: str, skip: int = 0, limit: int | None = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

В этом случае есть 3 параметра запроса:

  • needy, обязательный str.
  • skip, int со значением по умолчанию 0.
  • limit, необязательный int.

Совет

Вы также можете использовать Enum таким же образом, как и с параметрами пути.