Числовая валидация параметра пути в FastAPI

Использование с параметрами запросаQueryСпособ добавления валидации тот же; можно использоватьPathОбъявите числовую валидацию и метаданные для параметров пути.

Импорт Path

fromfastapiИмпортPath, fromtypingИмпорт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="ID продукта", description="ID продукта для получения", ge=1)],
):
    return {"item_id": item_id}

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

Валидация чисел

PathиQueryВсе поддерживают следующие параметры числовой валидации:

ПараметрЗначениеИсточник на английском
gtзнак большеgольше tем
geбольше или равноgольше или eавно
ltзнак меньшеlеньше tем
leменьше или равноlеньше или eавно

Больше или равно (ge)

Пределitem_idДолжно быть >= 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(ge=1)],  # item_id должен быть >= 1
):
    return {"item_id": 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 должен быть > 0 и <= 1000
    item_id: Annotated[int, Path(gt=0, le=1000)],
    # Параметры запроса также могут использовать числовую валидацию
    size: Annotated[float, Query(gt=0, lt=10.5)] = 5.0,
):
    return {"item_id": item_id, "size": size}

Валидация чисел с плавающей запятой

Числовая валидация также применяется к числам с плавающей запятой.gt(больше чем) иgeРазница (больше или равно) важна в сценариях с плавающей точкой:

Пример

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(ge=1, le=1000)],
    # size должен быть > 0 и < 10.5
    # 0.5 — допустимое значение, 0.0 и 0 — нет (потому что gt=0 строго больше 0)
    size: Annotated[float, Query(gt=0, lt=10.5)],
):
    return {"item_id": item_id, "size": size}

Смешивание параметров пути и параметров запроса

Когда вы используете обаPathиQueryпри использованииAnnotatedЭто может помочь избежать проблем с порядком параметров:

Пример

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    # После использования Annotated порядок параметров не важен
    item_id: Annotated[int, Path(title="ID продукта", ge=1, le=1000)],
    q: Annotated[str | None, Query(max_length=50)] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Итог

Ключевые моменты числовой валидации для параметров пути:

  • ИспользованиеAnnotated + PathОбъявление правил валидации для параметров пути
  • Числовая валидация:gt(больше),ge(больше или равно),lt(меньше),le(меньше или равно)
  • PathиQueryИспользование одних и тех же параметров валидации, включая валидацию строк (min_lengthи т. д.) и метаданные (title、descriptionи т.д.)
  • Параметры пути всегда обязательны, независимо от того, объявлено ли значение по умолчанию.
Другие расширения