FastAPI에서 Pydantic 모델이란 무엇입니까?

Question

Accepted Answer

**Pydantic 모델**은 데이터의 **구조, 타입, validation 규칙**을 정의하는 클래스(`BaseModel`을 상속)입니다. FastAPI는 이를 어디서나 사용합니다. 요청 본문, 응답 형태, 설정 등에 쓰이며, 타입 기반 설계의 핵심을 이룹니다.

## 모델 정의하기

```python
from pydantic import BaseModel, EmailStr, Field

class User(BaseModel):
    name: str
    email: EmailStr                          # 이메일 형식을 검증합니다
    age: int = Field(ge=0, le=120)            # 제약 조건: 0 <= age <= 120
    is_active: bool = True                    # 기본값
    tags: list[str] = []                      # 기본값이 있는 타입 지정 리스트
```

각 필드는 타입과 선택적 제약 조건/기본값을 선언합니다. Pydantic은 이 정의에 따라 데이터를 검증하고, 합리적인 경우 타입을 변환합니다.

## 자동 validation 및 파싱

```python
@app.post("/users")
def create_user(user: User):                  # FastAPI가 본문으로부터 User를 만들고 검증합니다
    return user                               # 여기서는 이미 검증됨
# 유효한 JSON → 타입이 지정된 User 객체; 무효 → 필드별 오류와 함께 자동 422
```

매개변수 타입으로 사용되면, FastAPI는 JSON 요청 본문을 모델로 파싱하고, 모든 필드를 **검증(validation)**하며, 무엇이 잘못되었는지 정확히 나열하는 구조화된 422 오류를 반환합니다. 모두 자동입니다.

## Pydantic이 제공하는 것

```text
✓ Validation — 타입 검사 + 제약 조건(길이, 범위, 형식), 명확한 오류
✓ 파싱/강제 변환 — "5" → 5, ISO 문자열 → datetime 등
✓ 직렬화 — model.model_dump() / model_dump_json() → dict/JSON
✓ 에디터 지원 — 모델 속성에 대한 완전한 자동완성 및 타입 검사
✓ 자체 문서화 — 모델이 자동 생성 문서에 사용되는 스키마(schema)를 정의함
```

## 단일 진실 공급원

```text
하나의 Pydantic 모델이 구동하는 것: 요청 validation, 응답 schema, OpenAPI 문서,
그리고 코드 내 타입 지정 접근 → 데이터 형태를 한 번만 정의하세요.
```

## 왜 중요한가

Pydantic 모델은 FastAPI의 초석입니다. API가 받고 반환하는 데이터를 정의하고 검증하는 방식이며, 거의 모든 FastAPI 기능이 이를 통해 흘러갑니다.

이를 이해하는 것이 필수적인 이유는, 단일 선언적 클래스만으로 자동 **validation**(보안과 견고함에 핵심적 — 절대 원시 입력을 신뢰하지 않음), 파싱/강제 변환, 직렬화, 에디터 지원을 제공하기 때문입니다.

또한 **단일 진실 공급원** 역할을 합니다. 하나의 모델이 요청 validation, 응답 형태, 자동 생성 문서를 모두 구동합니다.

이 타입 기반의 기본-검증(validate-by-default) 접근 방식—견고한 입력 validation과 명확한 오류 메시지를 사실상 무료로 얻는 것—은 FastAPI가 매우 생산적이고 안전한 주된 이유이며, Pydantic 모델을 반드시 익혀야 할 근본적 지식으로 만듭니다.