JSON 요청 본문을 어떻게 받습니까?

Question

Accepted Answer

FastAPI에서 JSON 요청 본문을 받으려면, **Pydantic 모델**로 타입이 지정된 함수 매개변수를 선언합니다. FastAPI는 본문을 읽고, JSON을 파싱하며, 모델에 따라 검증하고, 타입이 지정된 객체를 자동으로 전달합니다.

## 패턴

```python
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None      # 선택적 필드

@app.post("/items")
def create_item(item: Item):             # `item: Item` → JSON 본문을 읽고 검증
    # 여기서 `item`은 완전히 검증된 Item 객체입니다
    return {"name": item.name, "total": item.price * 1.1}
```

```json
// 클라이언트가 보내는 요청 본문:
{ "name": "Phone", "price": 999.0 }
```

`item: Item`을 선언하면 FastAPI가 요청 본문을 JSON으로 읽고, `Item`으로 파싱한 뒤 **검증(validation)**하도록 지시합니다. 함수는 타입이 지정된 유효한 객체를 받습니다. 잘못된 입력은 자동으로 거부됩니다:

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

## 본문 + 경로 + 쿼리를 함께

```python
@app.put("/items/{item_id}")
def update(item_id: int, item: Item, notify: bool = False):
    # item_id = 경로 매개변수, item = JSON 본문(Pydantic 모델), notify = 쿼리 매개변수
    # FastAPI가 타입/위치로 자동 구분합니다
```

FastAPI는 매개변수를 지능적으로 라우팅합니다: 경로 placeholder → 경로 매개변수, Pydantic 모델 → 요청 본문, 단순 타입 매개변수 → 쿼리 매개변수.

## 다중 본문 매개변수 / 부분 업데이트

```python
@app.patch("/items/{id}")
def patch(id: int, item: ItemUpdate):       # PATCH에는 모든 필드가 선택적인 모델 사용
    update_data = item.model_dump(exclude_unset=True)   # 클라이언트가 보낸 필드만
```

## 왜 중요한가

요청 본문을 받아 검증하는 것은 필수적입니다. 데이터를 생성하거나 업데이트하는 거의 모든 API가 이를 필요로 하며, FastAPI는 이를 놀랍도록 깔끔하게 만듭니다. Pydantic 모델 매개변수를 선언하기만 하면 자동 JSON 파싱, 완전한 **validation**(명확한 필드별 422 오류와 함께), 그리고 타입이 지정된 객체를 얻어, 다른 프레임워크가 요구하는 지루하고 오류가 많은 수동 파싱과 validation을 없애줍니다.

validation은 또한 핵심적인 **보안/견고성** 이점입니다. 잘못된 형식의 입력은 로직에 도달하기 전에 거부됩니다.

본문 모델을 정의하는 방법, FastAPI가 본문과 경로/쿼리 매개변수를 자동으로 구분하는 방식, 그리고 부분 업데이트를 위한 `exclude_unset` 같은 패턴을 이해하는 것은 어떤 쓰기(write) 엔드포인트를 구축하든 근본적인 일상 지식입니다.