如何接收 JSON 请求体？

Question

如何接收 JSON 请求体？

Accepted Answer

要在 FastAPI 中接收 JSON 请求体，您需要声明一个参数，其类型为 **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" }] }
```

## Body + path + 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 模型 → 请求体，简单类型参数 → 查询参数。

## 多个 body 参数 / 部分更新

```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 如何自动区分请求体与路径/查询参数，以及 `exclude_unset` 等用于部分更新的模式，是构建任何写入端点的基础日常知识。