Как вы получаете тело запроса JSON?

Question

Accepted Answer

Для получения тела запроса JSON в FastAPI вы объявляете параметр функции типизированный как **модель Pydantic**. FastAPI читает тело, парсит JSON, валидирует его по модели и передает вам типизированный объект — автоматически.

## Паттерн

```python
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None      # optional field

@app.post("/items")
def create_item(item: Item):             # `item: Item` → read & validate the JSON body
    # `item` is a fully-validated Item object here
    return {"name": item.name, "total": item.price * 1.1}
```

```json
// request body the client sends:
{ "name": "Phone", "price": 999.0 }
```

Объявление `item: Item` говорит FastAPI прочитать тело запроса как JSON, спарсить его в `Item` и **валидировать** — ваша функция получает типизированный, валидный объект. Неверные данные автоматически отклоняются:

```json
// POST { "name": "Phone" }  (missing price) → automatic 422:
{ "detail": [{ "loc": ["body", "price"], "msg": "field required" }] }
```

## Тело + путь + query вместе

```python
@app.put("/items/{item_id}")
def update(item_id: int, item: Item, notify: bool = False):
    # item_id = path param, item = JSON body (Pydantic model), notify = query param
    # FastAPI distinguishes them by type/location automatically
```

FastAPI интеллектуально маршрутизирует параметры: заполнитель пути → параметр пути, модель Pydantic → тело запроса, параметр простого типа → параметр query.

## Несколько параметров тела / частичные обновления

```python
@app.patch("/items/{id}")
def patch(id: int, item: ItemUpdate):       # use a model with all-optional fields for PATCH
    update_data = item.model_dump(exclude_unset=True)   # only fields the client sent
```

## Почему это важно

Получение и валидация тел запросов — это критически важно — почти каждый API, который создает или обновляет данные, нуждается в этом, и FastAPI делает это заметно чисто: объявление параметра модели Pydantic дает вам автоматический парсинг JSON, полную **валидацию** (с четкими ошибками на уровне поля 422), и типизированный объект, устраняя утомительный, подверженный ошибкам ручной парсинг и валидацию, которые требуют другие фреймворки.

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

Понимание того, как определить модель тела, как FastAPI автоматически различает тело от параметров пути/query, и паттерны, такие как `exclude_unset` для частичных обновлений — это фундаментальные ежедневные знания для построения любого эндпоинта записи.