FastAPI 시리즈 4화 - 요청(Request)과 응답(Response) 데이터 핸들링: Pydantic 모델 이해하기

FastAPI에서 Pydantic을 활용한 데이터 검증과 직렬화 처리 방식을 다룹니다. 요청 바디, 응답 스키마, 필드 유효성 검사까지 실전 예제를 중심으로 설명합니다.

 

---

 

FastAPI는 왜 Pydantic을 선택했을까?

 

FastAPI가 다른 Python 웹 프레임워크와 가장 뚜렷하게 다른 지점은 데이터 모델링에 Pydantic을 채택했다는 점입니다.

Pydantic은 단순한 데이터 클래스가 아니라 유효성 검사, 직렬화/역직렬화, 문서화까지 책임지는 핵심 엔진입니다.

 

즉, FastAPI는 “Pydantic 없이는 설명할 수 없는 프레임워크”입니다.

 

---

 

1. 요청 데이터 처리 – 

BaseModel

 사용법

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    age: int
    email: str

@app.post("/users")
def create_user(user: User):
    return {"message": f"User {user.name} created", "user": user}

 

▶ 클라이언트 요청 JSON 예시

{
  "name": "Alice",
  "age": 25,
  "email": "alice@example.com"
}

 

▶ 주요 특징

 

• User 클래스는 BaseModel을 상속받아 Pydantic 모델로 정의
• FastAPI는 이 모델을 기준으로 요청 바디를 자동 파싱하고 유효성 검사
• 타입 오류나 누락 필드가 있으면 자동으로 422 Unprocessable Entity 응답 반환

 

---

 

2. 필드 기본값과 선택 필드 처리

from typing import Optional

class User(BaseModel):
    name: str
    age: int = 18  # 기본값 설정
    email: Optional[str] = None  # 선택 필드

 

• Optional[str] = None: email은 생략 가능
• age = 18: 값이 없을 경우 기본값 18 자동 설정

 

이처럼 FastAPI는 **Pydantic 모델을 통해 데이터 계약(contract)**을 선언적으로 표현할 수 있습니다.

 

---

 

3. 응답(Response) 모델 지정

class UserOut(BaseModel):
    name: str
    email: str

@app.post("/users", response_model=UserOut)
def create_user(user: User):
    return user

 

• 클라이언트가 받는 응답 구조는 UserOut을 따름
• 서버 내부에서는 더 많은 필드를 다룰 수 있지만, 클라이언트에게는 필요한 필드만 노출

 

 

▶ 장점

 

• 보안성: 민감한 필드(예: 패스워드, 내부 ID 등)를 응답에서 제거 가능
• 가독성: 문서화 시 반환 구조가 명확해짐

 

---

 

4. 중첩 모델(Nested Models) 처리

class Address(BaseModel):
    city: str
    zip_code: str

class User(BaseModel):
    name: str
    address: Address

 

• Pydantic은 중첩 구조도 자연스럽게 지원
• 클라이언트 요청은 다음과 같이 구성됨

{
  "name": "Bob",
  "address": {
    "city": "Seoul",
    "zip_code": "12345"
  }
}

 

 

---

 

5. 유효성 검사와 예외 처리

from pydantic import Field

class Product(BaseModel):
    name: str
    price: float = Field(..., gt=0, description="Must be greater than zero")

 

• Field(..., gt=0): 필수 입력값이며 0보다 커야 함
• Swagger 문서에 조건과 설명이 자동 반영됨

 

💡 참고: FastAPI는 모든 유효성 검사 실패를 자동으로 잡아주고 422 오류로 반환합니다.

 

---

 

요약: Pydantic은 단순 검증 도구가 아니다

기능설명

유효성 검사	타입/범위/조건 기반 자동 필터링
문서화 연동	Swagger, Redoc에 API 스펙 자동 반영
중첩 모델링	복합 JSON 구조 자연스럽게 표현
응답 필터링	민감 정보 제거 및 외부용 응답 모델 구성 가능

FastAPI에서 Pydantic은 단순 보조가 아닌 중심 기술입니다.

모든 데이터 입출력 구조를 명세서처럼 선언하고, 검증하고, 문서화하는 흐름이 가능합니다.

 

---

 

다음 글 예고

 

FastAPI 시리즈 5화 - Swagger UI와 ReDoc: 자동 문서화의 힘

에서는 FastAPI가 어떻게 개발자의 손을 거의 거치지 않고도

완전한 API 문서 시스템을 자동으로 구성하는지,

Swagger UI와 ReDoc 활용법을 중심으로 다룹니다.