Как работает система type hints в FastAPI с Optional-полями и типами Union?

Type hints, Optional и Union в FastAPI

FastAPI использует Python type hints для трёх вещей сразу: валидация входных данных (через Pydantic), сериализация ответов и генерация OpenAPI-схемы. Понимание Optional и Union критично для корректной работы всего этого.

Optional[X] — поле может быть None

from typing import Optional
from pydantic import BaseModel

class JobFilter(BaseModel):
    title: str                        # обязательно, не может быть None
    location: Optional[str] = None    # необязательно, по умолчанию None
    min_salary: Optional[int] = None

В OpenAPI это транслируется в "location": {"anyOf": [{"type": "string"}, {"type": "null"}]}.

Разница: Optional без default vs с default

from pydantic import BaseModel
from typing import Optional

class Example(BaseModel):
    a: Optional[str]        # обязательное поле, но может быть null
    b: Optional[str] = None # необязательное поле, default = None

# Example(a=None)  — OK
# Example()        — ошибка: a обязательно
# Example(b="hi") — OK

Union — несколько допустимых типов

from typing import Union
from pydantic import BaseModel

class TextBlock(BaseModel):
    type: str = "text"
    content: str

class ImageBlock(BaseModel):
    type: str = "image"
    url: str
    alt: Optional[str] = None

class Message(BaseModel):
    blocks: list[Union[TextBlock, ImageBlock]]

Discriminated Union — быстрее и точнее

from typing import Annotated, Union, Literal
from pydantic import BaseModel, Field

class TextBlock(BaseModel):
    type: Literal["text"]
    content: str

class ImageBlock(BaseModel):
    type: Literal["image"]
    url: str

Block = Annotated[
    Union[TextBlock, ImageBlock],
    Field(discriminator="type"),
]

class Message(BaseModel):
    block: Block

# Pydantic выберет нужный тип по полю "type" без перебора вариантов

Python 3.10+ синтаксис

class Item(BaseModel):
    name: str
    description: str | None = None   # то же что Optional[str] = None
    price: int | float               # то же что Union[int, float]

Union в Query-параметрах

from fastapi import FastAPI, Query
from typing import Annotated

app = FastAPI()

@app.get("/search/")
async def search(
    q: Annotated[str | None, Query(min_length=2)] = None,
) -> dict:
    return {"query": q}

Подводные камни

• В Pydantic v2 Optional[str] без default делает поле обязательным (значение должно быть передано, пусть и None). В v1 поведение было другим — частый источник миграционных багов.
• Union[str, int] в Pydantic v2 попытается привести значение к первому подходящему типу; порядок элементов в Union важен.
• OpenAPI генерирует anyOf для Union — не все клиенты кодогенерации поддерживают это корректно.
• Discriminated Union требует, чтобы дискриминирующее поле было типа Literal — обычный str не сработает.
• При использовании | (Python 3.10+) в аргументах FastAPI убедитесь, что версия Pydantic >= 2 и Python >= 3.10; в старых окружениях получите TypeError.
• Тип Any из typing отключает валидацию Pydantic для конкретного поля — не используйте без крайней необходимости.
• Response model с Union и from_attributes=True может некорректно выбрать тип, если ORM-объект совместим с несколькими вариантами — используйте discriminated union.
• Optional[list[str]] и list[Optional[str]] — разные типы: первый означает «список или None», второй — «список, элементы которого могут быть None».

• Описывать type hints optional union только как термин и не показывать механизм на минимальном примере.
• Игнорировать ошибки, пустые данные, конкурентный доступ или границы транзакции.
• Не связывать поведение с официальным контрактом FastAPI и реальной эксплуатацией.

• Объясняет type hints optional union через последовательность действий, а не через набор ключевых слов.
• Приводит короткий кодовый пример или production-сценарий с ожидаемым поведением.
• Называет хотя бы один риск: производительность, безопасность, транзакции, память или сопровождение.