FastAPI와 Pydantic: 강력한 데이터 검증과 모델링

FastAPI 다이어그램

Pydantic은 Python에서 데이터 검증과 설정 관리를 위한 라이브러리로, FastAPI의 핵심 구성 요소입니다. 이 라이브러리는 타입 힌팅을 활용하여 런타임에 데이터 유효성을 검사하고, 복잡한 데이터 구조를 쉽게 모델링할 수 있게 해 줍니다.

Pydantic의 핵심 기능

데이터 모델 정의

Pydantic의 가장 기본적인 사용법은 `BaseModel`을 상속받아 사용자 정의 데이터 모델을 만드는 것입니다.

from pydantic import BaseModel

class Student(BaseModel):
    id: int
    name: str
    subjects: list[str] = []

이렇게 정의된 모델은 딕셔너리 데이터를 쉽게 파싱 할 수 있습니다.

data = {
    'id': 1,
    'name': 'Ravikumar',
    'subjects': ["Eng", "Maths", "Sci"],
}
student = Student(**data)

데이터 검증

Pydantic은 `Field` 함수를 사용하여 각 필드에 대한 세부적인 검증 규칙을 적용할 수 있습니다.

from pydantic import BaseModel, Field

class BookRequest(BaseModel):
    id: int
    title: str = Field(min_length=3)
    author: str
    description: str
    rating: int = Field(gt=-1, lt=6)  # -1보다 크고 6보다 작은 값

고급 검증

복잡한 검증 로직이 필요한 경우 `validator` 데코레이터를 사용할 수 있습니다.

from pydantic import BaseModel, validator

class Item(BaseModel):
    name: str

    @validator("name")
    def validate_name(cls, value):
        if len(value) < 3 or len(value) > 50:
            raise ValueError("Name must be between 3 and 50 characters")
        if not value.isalnum():
            raise ValueError("Name must contain only alphanumeric characters")
        return value

FastAPI와 Pydantic 통합

요청 본문 검증

FastAPI에서는 Pydantic 모델을 경로 함수의 매개변수로 사용하여 요청 본문을 자동으로 검증할 수 있습니다.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    id: int
    name: str
    price: float

@app.post("/items/")
async def create_item(item: Item):
    return item

이 코드는 `/items/` 엔드포인트로 들어오는 POST 요청의 본문이 `Item` 모델의 구조와 타입에 맞는지 자동으로 검증합니다.

응답 모델 정의

`response_model` 매개변수를 사용하여 API 응답의 구조를 정의할 수 있습니다.

from pydantic import BaseModel

class PredictOutput(BaseModel):
    prob: float
    prediction: int

@app.post("/pydantic", response_model=PredictOutput)
def pydantic_post(data_request: DataInput):
    return {"prob": 0.1, "prediction": 0}

쿼리 매개변수 검증

`Depends`를 사용하여 쿼리 매개변수도 Pydantic 모델로 검증할 수 있습니다.

from fastapi import FastAPI, Depends
from pydantic import BaseModel

app = FastAPI()

class ItemQueryParams(BaseModel):
    name: str
    price_min: float = 0
    price_max: float = 1000

@app.get("/items/")
async def read_items(params: ItemQueryParams = Depends()):
    return {"name": params.name, "price_min": params.price_min, "price_max": params.price_max}

실용적인 활용 팁

예제 데이터 선언

API 문서에 표시될 예제 데이터를 `Field`의 `examples` 매개변수를 통해 선언할 수 있습니다.

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(examples=["Foo"])
    description: str | None = Field(default=None, examples=["A very nice Item"])
    price: float = Field(examples=[35.4])
    tax: float | None = Field(default=None, examples=[3.2])

모델 변환 및 직렬화

Pydantic 모델은 다양한 형식으로 변환할 수 있습니다.

# 딕셔너리로 변환 (v2에서는 dict() 대신 model_dump() 사용)
item_dict = item.model_dump()

# JSON 문자열로 변환
item_json = item.model_dump_json()

중첩 모델

복잡한 데이터 구조를 표현하기 위해 모델을 중첩할 수 있습니다.

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

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

결론

Pydantic은 FastAPI와 함께 사용할 때 강력한 데이터 검증 및 모델링 기능을 제공합니다. 타입 힌팅을 활용한 직관적인 모델 정의, 자동 데이터 검증, 그리고 다양한 유효성 검사 기능을 통해 안전하고 견고한 API를 쉽게 구축할 수 있습니다. 이러한 기능은 개발 시간을 단축시키고, 코드의 가독성과 유지보수성을 크게 향상합니다.

 

[FastAPI] Pydantic (데이터 검증과 모델링)

 

2025.03.26 - [IT기술/파이썬 (python)] - FastAPI 비동기 처리(Async) 완벽 가이드: 고성능 웹 개발의 핵심

FastAPI 비동기 처리(Async) 완벽 가이드: 고성능 웹 개발의 핵심