중첩되고 복잡한 요청 본문을 어떻게 모델링합니까?

Question

Accepted Answer

Pydantic 모델은 **중첩(nest)**될 수 있습니다. 모델 필드가 그 자체로 다른 모델, 모델의 리스트, 또는 복잡한 타입이 될 수 있어, FastAPI가 깊게 구조화된 JSON(객체 안의 객체, 객체의 배열)을 자동으로 검증하게 합니다.

## 중첩 모델

```python
from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    zip: str

class User(BaseModel):
    name: str
    address: Address                    # 중첩 모델
    tags: list[str] = []                # 문자열 리스트
    addresses: list[Address] = []       # 중첩 모델의 리스트

@app.post("/users")
def create(user: User):                  # 전체 중첩 구조를 검증
    return user
```

```json
// FastAPI가 중첩된 address를 포함한 이 전체 구조를 검증합니다:
{ "name": "Ann",
  "address": { "street": "1 Main", "city": "NY", "zip": "10001" },
  "tags": ["vip"] }
```

다른 모델(또는 `list[Model]`)로 타입이 지정된 모델 필드는 재귀적으로 검증됩니다. 중첩 객체와 객체 배열이 모두 해당 schema에 대해 자동으로 검사됩니다.

## 복잡하고 특수한 타입

```python
from pydantic import BaseModel, HttpUrl, EmailStr
from datetime import datetime
from enum import Enum

class Status(str, Enum):                 # enum은 허용된 값으로 제한
    active = "active"
    inactive = "inactive"

class Item(BaseModel):
    url: HttpUrl                          # URL 형식 검증
    email: EmailStr                       # 이메일 형식 검증
    created: datetime                     # ISO 8601 문자열 → datetime 파싱
    status: Status                        # enum 값 중 하나여야 함
    metadata: dict[str, int]              # 타입 지정 dict
    coordinates: tuple[float, float]      # 타입 지정 tuple
```

Pydantic은 풍부한 타입을 처리합니다: enum(허용된 값으로 제한), `datetime`(ISO 문자열 파싱), `HttpUrl`/`EmailStr`(형식 validation), 타입 지정 dict/tuple — 모두 자동으로 검증됩니다.

## 제네릭 / 재사용 가능한 래퍼

```python
from typing import Generic, TypeVar
T = TypeVar("T")
class Paginated(BaseModel, Generic[T]):   # 재사용 가능한 제네릭 응답 래퍼
    items: list[T]
    total: int
# Paginated[User] → { items: [User...], total: N }
```

## 왜 중요한가

실제 API는 평면적인 데이터를 다루는 경우가 드뭅니다. 복잡하고 중첩된 구조(주소와 주문 리스트를 가진 사용자, 라인 아이템을 가진 주문, 설정 객체)를 처리하며, Pydantic의 **모델 중첩** 능력은 이러한 깊게 구조화된 요청 본문을 손쉽게 검증하게 합니다.

모델 필드가 다른 모델, 모델 리스트, 또는 풍부한 타입이 될 수 있고, FastAPI가 **전체 중첩 구조를 재귀적으로 자동 검증**한다는 것을 이해하는 것은 현실적이고 복잡한 입력을 안전하게 받는 API를 구축하는 데 중요합니다.

풍부한 타입 지원(제한된 값을 위한 enum, `datetime` 파싱, `HttpUrl`/`EmailStr` 형식 validation, 타입 지정 컬렉션)은 복잡한 데이터가 수동 검사 없이 올바르도록 더욱 보장합니다.

중첩되고 복잡한 본문(그리고 페이지네이션 같은 것을 위한 재사용 가능한 제네릭 래퍼)을 모델링하는 방법을 아는 것은 실제 애플리케이션이 요구하는 구조화된 데이터를 자동으로 제공되는 완전한 validation과 함께 처리하는 API를 구축하기 위한 실용 지식입니다. FastAPI의 Pydantic 기반 설계의 핵심 강점입니다.