Skip to content

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

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

Версия от 03.09.2026

Сложных моментов в уроке не обнаружено, поэтому я использовал освободившееся время, чтобы создать Инструмент для упрощения импорта в python

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

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

 

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

Обо мне

Параметры пути и числовые валидации

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

Импорт Path

Сначала импортируйте Path из fastapi и импортируйте Annotated:

from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
    q: Annotated[str | None, Query(alias="item-query")] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: str | None = Query(default=None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Примечание

FastAPI добавил поддержку Annotated (и начал рекомендовать его) в версии 0.95.0.

Если у вас более старая версия, при попытке использовать Annotated вы получите ошибки.

Убедитесь, что вы обновили версию FastAPI как минимум до 0.95.1, прежде чем использовать Annotated.

Объявление метаданных

Вы можете объявить все те же параметры, что и для Query.

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

from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
    q: Annotated[str | None, Query(alias="item-query")] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: str | None = Query(default=None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Примечание

Параметр пути всегда обязателен, так как он должен быть частью пути. Даже если вы объявите его с None или установите значение по умолчанию, это ни на что не повлияет, он всё равно будет всегда обязательным.

Упорядочивайте параметры как вам нужно

Совет

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

Допустим, вы хотите объявить параметр запроса q как обязательный str.

И вам не нужно объявлять что-либо ещё для этого параметра, поэтому вам на самом деле не нужно использовать Query.

Но вам всё ещё нужно использовать Path для параметра пути item_id. И вы не хотите использовать Annotated по какой-то причине.

Python выдаст ошибку, если вы поставите значение со значением «по умолчанию» перед значением, у которого нет «значения по умолчанию».

Но вы можете изменить их порядок и поставить значение без значения по умолчанию (параметр запроса q) первым.

Для FastAPI это не имеет значения. Он определит параметры по их именам, типам и объявлениям значений по умолчанию (Query, Path и т.д.), порядок ему не важен.

Итак, вы можете объявить вашу функцию как:

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(q: str, item_id: int = Path(title="The ID of the item to get")):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты
from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    q: str, item_id: Annotated[int, Path(title="The ID of the item to get")]
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Но имейте в виду, что если вы используете Annotated, у вас не будет этой проблемы, это не будет иметь значения, поскольку вы не используете значения по умолчанию параметров функции для Query() или Path().

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    q: str, item_id: Annotated[int, Path(title="The ID of the item to get")]
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(q: str, item_id: int = Path(title="The ID of the item to get")):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Упорядочивайте параметры как вам нужно, трюки

Совет

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

Вот маленький трюк, который может пригодиться, но он вам не часто понадобится.

Если вы хотите:

  • объявить параметр запроса q без Query и без значения по умолчанию
  • объявить параметр пути item_id с помощью Path
  • расположить их в другом порядке
  • не использовать Annotated

...у Python есть для этого небольшой специальный синтаксис.

Передайте * в качестве первого параметра функции.

Python ничего не сделает с этим *, но он будет знать, что все следующие параметры должны передаваться как именованные аргументы (пары ключ-значение), также известные как kwargs. Даже если у них нет значения по умолчанию.

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(*, item_id: int = Path(title="The ID of the item to get"), q: str):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты
from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")], q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Лучше с Annotated

Имейте в виду, что если вы используете Annotated, поскольку вы не используете значения по умолчанию параметров функции, у вас не будет этой проблемы, и вам, вероятно, не понадобится использовать *.

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")], q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(*, item_id: int = Path(title="The ID of the item to get"), q: str):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Числовые валидации: больше или равно

С Query и Path (и другими, которые вы увидите позже) вы можете объявлять числовые ограничения.

Здесь, с ge=1, item_id должен быть целым числом «greater than or equal» (больше или равно) 1.

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get", ge=1)], q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *, item_id: int = Path(title="The ID of the item to get", ge=1), q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Числовые валидации: больше и меньше или равно

То же самое применимо для:

  • gt: greater than (больше чем)
  • le: less than or equal (меньше или равно)
from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get", gt=0, le=1000)],
    q: str,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: int = Path(title="The ID of the item to get", gt=0, le=1000),
    q: str,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Числовые валидации: числа с плавающей точкой, больше и меньше

Числовые валидации также работают для значений float.

Вот где становится важным уметь объявлять gt, а не только ge. Поскольку с его помощью вы можете требовать, например, чтобы значение было больше 0, даже если оно меньше 1.

Таким образом, 0.5 будет допустимым значением. Но 0.0 или 0 — нет.

И то же самое для lt.

from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: Annotated[int, Path(title="The ID of the item to get", ge=0, le=1000)],
    q: str,
    size: Annotated[float, Query(gt=0, lt=10.5)],
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    if size:
        results.update({"size": size})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: int = Path(title="The ID of the item to get", ge=0, le=1000),
    q: str,
    size: float = Query(gt=0, lt=10.5),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    if size:
        results.update({"size": size})
    return results

Итог

С Query, Path (и другими, которые вы ещё не видели) вы можете объявлять метаданные и строковые валидации так же, как и в разделе Параметры запроса и валидация строк.

И вы также можете объявлять числовые валидации:

  • gt: greater than (больше чем)
  • ge: greater than or equal (больше или равно)
  • lt: less than (меньше чем)
  • le: less than or equal (меньше или равно)

Примечание

Query, Path и другие классы, которые вы увидите позже, являются подклассами общего класса Param.

Все они используют одни и те же параметры для дополнительной валидации и метаданных, которые вы видели.

Технические детали

Когда вы импортируете Query, Path и другие из fastapi, на самом деле это функции.

Которые при вызове возвращают экземпляры классов с тем же именем.

Итак, вы импортируете Query, который является функцией. И когда вы вызываете её, она возвращает экземпляр класса, также называемого Query.

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

Таким образом, вы можете использовать свой обычный редактор и инструменты программирования без необходимости добавлять пользовательские конфигурации, чтобы игнорировать эти ошибки.