Skip to content

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

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

Версия от 03.09.2026

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

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

 

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

Обо мне

Параметры запроса и валидация строк

FastAPI позволяет объявлять дополнительную информацию и валидацию для ваших параметров.

Возьмём в качестве примера это приложение:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/")
async def read_items(q: str | None = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Параметр запроса q имеет тип str | None, что означает, что он имеет тип str, но также может быть None, и действительно, значение по умолчанию — None, поэтому FastAPI поймёт, что он необязательный.

Примечание

FastAPI поймёт, что значение q не является обязательным, из-за значения по умолчанию = None.

Наличие str | None позволит вашему редактору обеспечить лучшую поддержку и обнаружение ошибок.

Дополнительная валидация

Мы собираемся сделать так, чтобы, несмотря на то что q необязателен, при его передаче его длина не превышала 50 символов.

Импорт Query и Annotated

Для этого сначала импортируйте:

  • Query из fastapi
  • Annotated из typing
from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(max_length=50)] = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str | None = Query(default=None, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Примечание

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

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

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

Использование Annotated в типе для параметра q

Помните, я говорил вам раньше, что Annotated можно использовать для добавления метаданных к вашим параметрам во Введении в типы Python?

Теперь пришло время использовать его с FastAPI. 🚀

У нас была такая аннотация типа:

q: str | None = None

Что мы сделаем, так это обернём её в Annotated, чтобы получилось:

q: Annotated[str | None] = None

Обе эти версии означают одно и то же: q — это параметр, который может быть str или None, и по умолчанию он равен None.

Теперь перейдём к самому интересному. 🎉

Добавление Query в Annotated для параметра q

Теперь, когда у нас есть этот Annotated, куда мы можем поместить больше информации (в данном случае некоторую дополнительную валидацию), добавьте Query внутрь Annotated и установите параметр max_length равным 50:

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(max_length=50)] = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str | None = Query(default=None, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Обратите внимание, что значение по умолчанию по-прежнему None, поэтому параметр по-прежнему необязательный.

Но теперь, имея Query(max_length=50) внутри Annotated, мы сообщаем FastAPI, что хотим, чтобы для этого значения была дополнительная валидация, мы хотим, чтобы оно имело максимум 50 символов. 😎

Совет

Здесь мы используем Query(), потому что это параметр запроса. Позже мы увидим другие, такие как Path(), Body(), Header() и Cookie(), которые также принимают те же аргументы, что и Query().

Теперь FastAPI будет:

  • Валидировать данные, убедившись, что максимальная длина составляет 50 символов
  • Показывать понятную ошибку клиенту, когда данные недействительны
  • Документировать параметр в схеме OpenAPI операции пути (поэтому он появится в автоматическом интерфейсе документации)

Альтернатива (старая): Query как значение по умолчанию

Предыдущие версии FastAPI (до 0.95.0) требовали использовать Query в качестве значения по умолчанию для вашего параметра вместо помещения его в Annotated; есть большая вероятность, что вы увидите код, использующий его, поэтому я объясню это вам.

Совет

Для нового кода и всегда, когда это возможно, используйте Annotated, как объяснено выше. Есть несколько преимуществ (объяснённых ниже) и никаких недостатков. 🍰

Вот как вы бы использовали Query() в качестве значения по умолчанию для параметра функции, установив параметр max_length равным 50:

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str | None = Query(default=None, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты
from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(max_length=50)] = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Как и в этом случае (без использования Annotated), нам нужно заменить значение по умолчанию None в функции на Query(), теперь нам нужно установить значение по умолчанию с помощью параметра Query(default=None), это служит той же цели определения значения по умолчанию (по крайней мере, для FastAPI).

Итак:

q: str | None = Query(default=None)

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

q: str | None = None

Но версия с Query явно объявляет его как параметр запроса.

Затем мы можем передать больше параметров в Query. В данном случае параметр max_length, который применяется к строкам:

q: str | None = Query(default=None, max_length=50)

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

Query как значение по умолчанию или в Annotated

Имейте в виду, что при использовании Query внутри Annotated вы не можете использовать параметр default для Query.

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

Например, это недопустимо:

q: Annotated[str, Query(default="rick")] = "morty"

...потому что неясно, должно ли значение по умолчанию быть "rick" или "morty".

Поэтому вы бы использовали (предпочтительно):

q: Annotated[str, Query()] = "rick"

...или в старых кодовых базах вы найдёте:

q: str = Query(default="rick")

Преимущества Annotated

Использование Annotated рекомендуется вместо значения по умолчанию в параметрах функции, это лучше по нескольким причинам. 🤓

Значение по умолчанию для параметра функции — это фактическое значение по умолчанию, что более интуитивно понятно в Python в целом. 😌

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

Когда вы не используете Annotated и вместо этого используете (старый) стиль со значением по умолчанию, если вы вызовете эту функцию без FastAPI в других местах, вам нужно помнить, чтобы передавать аргументы функции, чтобы она работала правильно, иначе значения будут отличаться от ожидаемых (например, QueryInfo или что-то подобное вместо str). И ваш редактор не будет жаловаться, и Python не будет жаловаться при запуске этой функции, только когда операции внутри неё завершатся ошибкой.

Поскольку Annotated может иметь более одной аннотации метаданных, вы теперь можете даже использовать одну и ту же функцию с другими инструментами, такими как Typer. 🚀

Добавление дополнительных валидаций

Вы также можете добавить параметр min_length:

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Annotated[str | None, Query(min_length=3, max_length=50)] = None,
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str | None = Query(default=None, min_length=3, max_length=50)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Добавление регулярных выражений

Вы можете определить регулярное выражение pattern, которому должен соответствовать параметр:

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Annotated[
        str | None, Query(min_length=3, max_length=50, pattern="^fixedquery$")
    ] = None,
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: str | None = Query(
        default=None, min_length=3, max_length=50, pattern="^fixedquery$"
    ),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Этот конкретный шаблон регулярного выражения проверяет, что полученное значение параметра:

  • ^: начинается со следующих символов, перед ними нет символов.
  • fixedquery: имеет точное значение fixedquery.
  • $: заканчивается здесь, после fixedquery нет никаких других символов.

Если вы чувствуете себя потерянным со всеми этими идеями «регулярных выражений», не волнуйтесь. Это сложная тема для многих людей. Вы всё ещё можете делать много вещей, пока не нуждаясь в регулярных выражениях.

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

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

Вы, конечно, можете использовать значения по умолчанию, отличные от None.

Допустим, вы хотите объявить параметр запроса q с min_length равным 3 и значением по умолчанию "fixedquery":

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[str, Query(min_length=3)] = "fixedquery"):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str = Query(default="fixedquery", min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Примечание

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

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

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

q: str

вместо:

q: str | None = None

Но теперь мы объявляем его с помощью Query, например так:

q: Annotated[str | None, Query(min_length=3)] = None

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

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[str, Query(min_length=3)]):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str = Query(min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Обязательный, может быть None

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

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

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(min_length=3)]):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str | None = Query(min_length=3)):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Список параметров запроса / несколько значений

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

Например, чтобы объявить параметр запроса q, который может появляться в URL несколько раз, вы можете написать:

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[list[str] | None, Query()] = None):
    query_items = {"q": q}
    return query_items
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: list[str] | None = Query(default=None)):
    query_items = {"q": q}
    return query_items

Тогда с URL вида:

http://localhost:8000/items/?q=foo&q=bar

вы получите несколько значений параметров запроса q (foo и bar) в виде списка Python внутри вашей функции операции пути, в параметре функции q.

Таким образом, ответом на этот URL будет:

{
  "q": [
    "foo",
    "bar"
  ]
}

Совет

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

Интерактивная документация API обновится соответствующим образом, чтобы разрешить несколько значений:

Список параметров запроса / несколько значений со значениями по умолчанию

Вы также можете определить список значений по умолчанию, если ни один не предоставлен:

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[list[str], Query()] = ["foo", "bar"]):
    query_items = {"q": q}
    return query_items
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: list[str] = Query(default=["foo", "bar"])):
    query_items = {"q": q}
    return query_items

Если вы перейдёте по адресу:

http://localhost:8000/items/

значение по умолчанию для q будет: ["foo", "bar"], и ваш ответ будет:

{
  "q": [
    "foo",
    "bar"
  ]
}

Использование просто list

Вы также можете использовать list напрямую вместо list[str]:

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


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

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: list = Query(default=[])):
    query_items = {"q": q}
    return query_items

Примечание

Имейте в виду, что в этом случае FastAPI не будет проверять содержимое списка.

Например, list[int] проверил бы (и задокументировал бы), что содержимое списка состоит из целых чисел. Но list сам по себе — нет.

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

Вы можете добавить больше информации о параметре.

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

Примечание

Имейте в виду, что разные инструменты могут иметь разный уровень поддержки OpenAPI.

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

Вы можете добавить title:

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Annotated[str | None, Query(title="Query string", min_length=3)] = None,
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, title="Query string", min_length=3),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

И description:

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Annotated[
        str | None,
        Query(
            title="Query string",
            description="Query string for the items to search in the database that have a good match",
            min_length=3,
        ),
    ] = None,
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: str | None = Query(
        default=None,
        title="Query string",
        description="Query string for the items to search in the database that have a good match",
        min_length=3,
    ),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Параметры псевдонимов

Представьте, что вы хотите, чтобы параметр назывался item-query.

Например, в:

http://127.0.0.1:8000/items/?item-query=foobaritems

Но item-query не является допустимым именем переменной Python.

Ближайшим будет item_query.

Но вам всё равно нужно, чтобы он был точно item-query...

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

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


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

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str | None = Query(default=None, alias="item-query")):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Устаревшие параметры

Теперь допустим, вам больше не нравится этот параметр.

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

Затем передайте параметр deprecated=True в Query:

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Annotated[
        str | None,
        Query(
            alias="item-query",
            title="Query string",
            description="Query string for the items to search in the database that have a good match",
            min_length=3,
            max_length=50,
            pattern="^fixedquery$",
            deprecated=True,
        ),
    ] = None,
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: str | None = Query(
        default=None,
        alias="item-query",
        title="Query string",
        description="Query string for the items to search in the database that have a good match",
        min_length=3,
        max_length=50,
        pattern="^fixedquery$",
        deprecated=True,
    ),
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Документация покажет это так:

Исключение параметров из OpenAPI

Чтобы исключить параметр запроса из сгенерированной схемы OpenAPI (и, следовательно, из систем автоматической документации), установите параметр include_in_schema у Query в False:

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    hidden_query: Annotated[str | None, Query(include_in_schema=False)] = None,
):
    if hidden_query:
        return {"hidden_query": hidden_query}
    else:
        return {"hidden_query": "Not found"}
🤓 Другие версии и варианты

Совет

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

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    hidden_query: str | None = Query(default=None, include_in_schema=False),
):
    if hidden_query:
        return {"hidden_query": hidden_query}
    else:
        return {"hidden_query": "Not found"}

Пользовательская валидация

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

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

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

Совет

В Pydantic также есть BeforeValidator и другие. 🤓

Например, этот пользовательский валидатор проверяет, что ID элемента начинается с isbn- для номера книги ISBN или с imdb- для URL-ID фильма IMDB:

import random
from typing import Annotated

from fastapi import FastAPI
from pydantic import AfterValidator

app = FastAPI()

data = {
    "isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
    "imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
    "isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
}


def check_valid_id(id: str):
    if not id.startswith(("isbn-", "imdb-")):
        raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
    return id


@app.get("/items/")
async def read_items(
    id: Annotated[str | None, AfterValidator(check_valid_id)] = None,
):
    if id:
        item = data.get(id)
    else:
        id, item = random.choice(list(data.items()))
    return {"id": id, "name": item}

Примечание

Это доступно в Pydantic версии 2 или выше. 😎

Совет

Если вам нужно выполнить какую-либо валидацию, требующую взаимодействия с каким-либо внешним компонентом, например с базой данных или другим API, вместо этого вам следует использовать зависимости FastAPI, о которых вы узнаете позже.

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

Понимание этого кода

Важно только использование AfterValidator с функцией внутри Annotated. Не стесняйтесь пропустить эту часть. 🤸


Но если вам интересен этот конкретный пример кода и вы всё ещё увлечены, вот некоторые дополнительные детали.

Строка с value.startswith()

Вы заметили? Строка, использующая value.startswith(), может принимать кортеж, и она проверит каждое значение в кортеже:

# Код выше опущен 👆

def check_valid_id(id: str):
    if not id.startswith(("isbn-", "imdb-")):
        raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
    return id

# Код ниже опущен 👇
👀 Предпросмотр полного файла
import random
from typing import Annotated

from fastapi import FastAPI
from pydantic import AfterValidator

app = FastAPI()

data = {
    "isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
    "imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
    "isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
}


def check_valid_id(id: str):
    if not id.startswith(("isbn-", "imdb-")):
        raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
    return id


@app.get("/items/")
async def read_items(
    id: Annotated[str | None, AfterValidator(check_valid_id)] = None,
):
    if id:
        item = data.get(id)
    else:
        id, item = random.choice(list(data.items()))
    return {"id": id, "name": item}

Случайный элемент

С помощью data.items() мы получаем итерируемый объект с кортежами, содержащими ключ и значение для каждого элемента словаря.

Мы преобразуем этот итерируемый объект в настоящий list с помощью list(data.items()).

Затем с помощью random.choice() мы можем получить случайное значение из списка, то есть мы получаем кортеж (id, name). Это будет что-то вроде ("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy").

Затем мы присваиваем эти два значения из кортежа переменным id и name.

Таким образом, если пользователь не предоставил ID элемента, он всё равно получит случайное предложение.

...мы делаем всё это в одной простой строке. 🤯 Разве вы не любите Python? 🐍

# Код выше опущен 👆

@app.get("/items/")
async def read_items(
    id: Annotated[str | None, AfterValidator(check_valid_id)] = None,
):
    if id:
        item = data.get(id)
    else:
        id, item = random.choice(list(data.items()))
    return {"id": id, "name": item}
👀 Предпросмотр полного файла
import random
from typing import Annotated

from fastapi import FastAPI
from pydantic import AfterValidator

app = FastAPI()

data = {
    "isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
    "imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
    "isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
}


def check_valid_id(id: str):
    if not id.startswith(("isbn-", "imdb-")):
        raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
    return id


@app.get("/items/")
async def read_items(
    id: Annotated[str | None, AfterValidator(check_valid_id)] = None,
):
    if id:
        item = data.get(id)
    else:
        id, item = random.choice(list(data.items()))
    return {"id": id, "name": item}

Итог

Вы можете объявлять дополнительные валидации и метаданные для ваших параметров.

Общие валидации и метаданные:

  • alias
  • title
  • description
  • deprecated

Валидации, специфичные для строк:

  • min_length
  • max_length
  • pattern

Пользовательские валидации с использованием AfterValidator.

В этих примерах вы увидели, как объявлять валидации для значений str.

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