Pydantic Field : 데이터 유효성 검사

Pydantic의 Field는 모델 필드를 정의할 때 사용되는 핵심 기능입니다. Field를 통해 데이터 유효성 검사, 기본값 설정, 제약 조건 등을 세밀하게 제어할 수 있습니다.

기본 Field 매개변수

from pydantic import BaseModel, Field
from typing import Optional

class User(BaseModel):
    # 기본적인 Field 사용
    name: str = Field(
        default="John Doe",           # 기본값 설정
        min_length=2,                 # 최소 길이
        max_length=50,                # 최대 길이
        description="사용자의 이름"    # 필드 설명
    )

    age: int = Field(
        gt=0,                        # 0보다 큰 값
        lt=150,                      # 150보다 작은 값
        description="사용자의 나이"
    )

제약 조건 매개변수

class Product(BaseModel):
    # 숫자 관련 제약조건
    price: float = Field(
        ge=0.0,          # greater than or equal (>=)
        le=1000000.0,    # less than or equal (<=)
    )

    # 문자열 패턴 매칭
    code: str = Field(
        regex="^[A-Z]{2}[0-9]{4}$"  # 정규표현식 패턴
    )

    # 리스트 길이 제한
    tags: list[str] = Field(
        min_items=1,     # 최소 아이템 수
        max_items=5      # 최대 아이템 수
    )

고급 Field 매개변수

from datetime import datetime
from typing import Any

class AdvancedModel(BaseModel):
    # 동적 기본값
    created_at: datetime = Field(
        default_factory=datetime.now,  # 함수를 통한 기본값 생성
    )

    # 상수값 정의
    status: str = Field(
        const=True,                    # 값 변경 불가
        default="ACTIVE"
    )

    # JSON 스키마 커스터마이징
    metadata: dict[str, Any] = Field(
        title="메타데이터",
        examples=[{"key": "value"}],    # 예시 데이터
    )

의존성 있는 Field 검증

from pydantic import validator

class Order(BaseModel):
    quantity: int = Field(gt=0)
    unit_price: float = Field(gt=0)
    total_price: float = Field()

    @validator("total_price")
    def calculate_total_price(cls, v, values):
        quantity = values.get("quantity")
        unit_price = values.get("unit_price")
        if quantity and unit_price:
            return quantity * unit_price
        return v

복잡한 검증 규칙

from typing import Union
from pydantic import EmailStr

class ComplexModel(BaseModel):
    # 여러 타입 허용
    identifier: Union[int, str] = Field(
        union_mode="smart",  # 타입 추론 모드
    )

    # 이메일 검증
    email: EmailStr = Field(
        description="유효한 이메일 주소"
    )

    # 중첩된 제약조건
    score: float = Field(
        ge=0.0,
        le=100.0,
        multiple_of=0.5,  # 0.5의 배수만 허용
    )

에러 메시지 커스터마이징

class CustomErrorModel(BaseModel):
    username: str = Field(
        min_length=3,
        max_length=20,
        regex="^[a-zA-Z0-9_]*$",
        error_messages={
            "min_length": "사용자명은 최소 3자 이상이어야 합니다",
            "max_length": "사용자명은 최대 20자를 초과할 수 없습니다",
            "regex": "사용자명은 영문자, 숫자, 언더스코어만 포함할 수 있습니다"
        }
    )

JSON 스키마 커스터마이징

class SchemaModel(BaseModel):
    data: dict = Field(
        title="데이터",
        description="JSON 형식의 데이터",
        examples=[
            {"id": 1, "name": "example"},
            {"id": 2, "name": "test"}
        ],
        schema_extra={
            "examples": [
                {
                    "id": 1,
                    "name": "example"
                }
            ]
        }
    )

실전 활용 예시

from typing import Optional
from datetime import date

class Employee(BaseModel):
    id: int = Field(gt=0, description="직원 고유 ID")
    name: str = Field(
        min_length=2,
        max_length=50,
        regex="^[가-힣a-zA-Z ]*$",
        description="직원 이름"
    )
    email: EmailStr = Field(description="회사 이메일")
    department: str = Field(
        default="General",
        description="소속 부서"
    )
    hire_date: date = Field(
        default_factory=date.today,
        description="입사일"
    )
    salary: float = Field(
        gt=0,
        multiple_of=100,
        description="연봉"
    )
    is_active: bool = Field(
        default=True,
        description="재직 여부"
    )
    skills: list[str] = Field(
        default_factory=list,
        min_items=1,
        max_items=10,
        description="보유 기술"
    )

    class Config:
        schema_extra = {
            "example": {
                "id": 1,
                "name": "홍길동",
                "email": "hong@company.com",
                "department": "개발팀",
                "hire_date": "2024-01-01",
                "salary": 50000000,
                "is_active": True,
                "skills": ["Python", "FastAPI", "SQL"]
            }
        }

Field의 다양한 매개변수를 활용하면 데이터 모델을 더욱 견고하게 정의할 수 있으며, API 문서화도 자동으로 생성됩니다. 특히 FastAPI와 함께 사용할 때 그 진가를 발휘하며, 런타임에서의 데이터 유효성 검사를 통해 애플리케이션의 안정성을 크게 향상시킬 수 있습니다.