FastAPI와 Pydantic을 활용해 타입 안전한 REST API를 빠르게 구축하는 방법을 소개합니다. 자동 데이터 검증, API 문서 생성, 실전 예제 코드까지 초보자도 쉽게 따라할 수 있는 완벽 가이드입니다.
FastAPI와 Pydantic이란?¶
FastAPI는 Python 3.7+에서 사용할 수 있는 현대적이고 빠른 웹 프레임워크입니다. 가장 큰 특징은 Pydantic을 활용한 자동 데이터 검증과 타입 힌트 기반의 개발 경험이에요. Pydantic은 Python의 타입 어노테이션을 사용해 데이터를 검증하고 파싱하는 라이브러리로, 런타임에서 타입 안전성을 보장해줍니다.
기존 Flask나 Django와 비교했을 때 FastAPI는 비동기 처리를 기본으로 지원하고, 자동으로 API 문서(Swagger UI)를 생성해주며, 타입 체킹으로 개발 중 버그를 미리 잡아낼 수 있다는 장점이 있습니다. 특히 초보자도 쉽게 배울 수 있으면서도 프로덕션 레벨의 성능을 제공한다는 점이 매력적이죠.
개발 환경 설정하기¶
먼저 필요한 패키지를 설치해볼게요. 가상환경을 만들고 FastAPI와 ASGI 서버인 uvicorn을 설치합니다.
bash
가상환경 생성 및 활성화¶
python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate
필요한 패키지 설치¶
pip install fastapi uvicorn[standard] pydantic
설치가 완료되면 프로젝트 폴더에 main.py 파일을 생성하세요. FastAPI의 핵심은 간결함입니다. 몇 줄의 코드만으로도 동작하는 API 서버를 만들 수 있어요. 타입 힌트를 사용하면 FastAPI가 자동으로 요청 데이터를 검증하고, 응답 형식을 문서화해줍니다.
첫 번째 API 엔드포인트 만들기¶
가장 기본적인 "Hello World" API부터 시작해볼까요? 아래 코드를 main.py에 작성하세요.
python from fastapi import FastAPI from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel): name: str price: float is_offer: bool = False
@app.get("/") def read_root(): return {"message": "Hello World"}
@app.get("/items/{item_id}") def read_item(item_id: int, q: str = None): return {"item_id": item_id, "q": q}
@app.post("/items/") def create_item(item: Item): return {"item_name": item.name, "item_price": item.price}
이 코드에서 Item 클래스는 Pydantic 모델입니다. name은 문자열, price는 실수형이어야 하며, is_offer는 선택적인 불린 값이에요. FastAPI는 이 정보를 바탕으로 자동으로 데이터를 검증합니다. 만약 잘못된 타입의 데이터가 들어오면 자동으로 에러 응답을 반환하죠.
서버를 실행하려면 터미널에서 다음 명령어를 입력하세요:
bash uvicorn main:app --reload
--reload 옵션은 코드 변경 시 자동으로 서버를 재시작해줍니다. 개발할 때 정말 편리한 기능이에요!
Pydantic으로 타입 안전성 확보하기¶
Pydantic의 진가는 복잡한 데이터 구조를 다룰 때 드러납니다. 중첩된 모델, 리스트, 선택적 필드 등을 타입 안전하게 처리할 수 있어요.
python from pydantic import BaseModel, Field, EmailStr from typing import Optional, List from datetime import datetime
class User(BaseModel): username: str = Field(..., min_length=3, max_length=50) email: EmailStr age: int = Field(..., gt=0, lt=120) created_at: datetime = Field(default_factory=datetime.now) tags: List[str] = []
class Product(BaseModel): name: str price: float = Field(..., gt=0, description="가격은 0보다 커야 합니다") seller: User stock: Optional[int] = None
@app.post("/products/") def create_product(product: Product): return { "product_name": product.name, "seller_username": product.seller.username, "total_value": product.price * (product.stock or 0) }
Field를 사용하면 더 세밀한 검증 규칙을 정의할 수 있습니다. min_length, max_length, gt(greater than), lt(less than) 등의 옵션으로 데이터 범위를 제한할 수 있어요. EmailStr은 이메일 형식을 자동으로 검증해주는 특수 타입입니다 (단, pip install pydantic[email] 설치 필요).
중요한 점은 이 모든 검증이 자동으로 이루어진다는 거예요. 개발자가 일일이 if문으로 체크할 필요가 없죠. 잘못된 데이터가 들어오면 FastAPI가 422 에러와 함께 어떤 필드가 문제인지 자세히 알려줍니다.
자동 생성되는 API 문서 활용하기¶
FastAPI의 킬러 기능 중 하나는 자동으로 생성되는 대화형 API 문서입니다. 서버를 실행한 후 브라우저에서 http://127.0.0.1:8000/docs에 접속해보세요. Swagger UI 기반의 멋진 문서가 자동으로 생성되어 있을 거예요!
이 문서에서는 각 엔드포인트를 직접 테스트해볼 수 있습니다. "Try it out" 버튼을 클릭하고 데이터를 입력하면 실제 API 요청을 보낼 수 있어요. 응답도 바로 확인할 수 있죠. 또한 http://127.0.0.1:8000/redoc에서는 ReDoc 스타일의 문서도 볼 수 있습니다.
실전 팁: - 각 엔드포인트에 docstring을 추가하면 문서에 설명이 자동으로 표시됩니다 - response_model 파라미터로 응답 형식을 명시하면 더 정확한 문서가 생성됩니다 - tags 파라미터로 API를 그룹화하면 문서가 더 깔끔해집니다
타입 안전성, 자동 검증, 훌륭한 문서화를 동시에 얻을 수 있는 FastAPI와 Pydantic의 조합은 현대적인 API 개발의 표준이 되어가고 있습니다. 5분이면 충분히 시작할 수 있으니 지금 바로 도전해보세요!
이 글은 AI가 자동으로 작성했습니다.