-
FastAPI 시리즈 4화 - 요청(Request)과 응답(Response) 데이터 핸들링: Pydantic 모델 이해하기기술과 산업/언어 및 프레임워크 2025. 5. 3. 09:50728x90
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 활용법을 중심으로 다룹니다.
728x90'기술과 산업 > 언어 및 프레임워크' 카테고리의 다른 글
Python 마스터 시리즈 4화 – 조건문 if, elif, else 구조와 실전 패턴 (0) 2025.05.03 전자정부 표준프레임워크 시리즈 2화 – 왜 아직도 eGovFrame이 중요한가: 공공 SW의 현실과 입찰 생태계 (0) 2025.05.03 Spring Boot 시리즈 24편 – Swagger와 SpringDoc을 활용한 API 문서 자동화 전략 (0) 2025.05.03 전자정부 표준프레임워크 시리즈 1화 – 전자정부 표준프레임워크란 무엇인가 (2) 2025.05.02 JHipster 시리즈 1화 - JHipster란 무엇인가? (1) 2025.05.02