FastAPI는 Pydantic을 통해 데이터를 정의하고 검증합니다. 코드를 작성하는 순간 자동으로 데이터 검증과 JSON 직렬화가 이루어집니다.

1. Pydantic이란?

Pydantic은 Python 타입 힌트를 기반으로 데이터를 검증하고 직렬화하는 라이브러리입니다. FastAPI가 내부적으로 사용하여 API 요청/응답 데이터를 자동으로 처리합니다.

BaseModel 기초

from pydantic import BaseModel

class SensorData(BaseModel):
    sensor: str
    value: float
    unit: str
    status: str

이 정의만으로 아래 기능이 자동으로 동작합니다:

• JSON 파싱/직렬화 자동화
• 타입 에러 시 422 응답 자동 반환
• OpenAPI 도큰먼트 자동 생성

2. Enum으로 타입 안전성 확보

SensorType, ProcessStage 같은 Enum을 사용하면 허용되지 않는 값을 사전에 차단할 수 있습니다.

from enum import Enum

class SensorType(str, Enum):
    PH = "ph"
    TURBIDITY = "turbidity"
    FLOW = "flow"
    TEMP = "temp"

class SensorStatus(str, Enum):
    NORMAL = "normal"
    WARNING = "warning"
    DANGER = "danger"

class ProcessStage(str, Enum):
    PRIMARY_SETTLING = "primary_settling"
    AERATION = "aeration"
    SECONDARY_SETTLING = "secondary_settling"
    NITRIFICATION = "nitrification"
    DISINFECTION = "disinfection"

str 상속의 의미: str를 함께 상속하면 JSON 직렬화 시 "ph" 같은 문자열로 처리됩니다. SensorType.PH가 아니라 "ph"로 직렬화됩니다.

실제 효과: /api/history?sensor=invalid와 같은 잘못된 값 전달 시 FastAPI가 422 에러를 자동 반환합니다.

3. Field로 검증 규치기

Field를 사용하면 값의 범위나 설명을 모델에 직접 정의할 수 있습니다.

from pydantic import BaseModel, Field

class StageParams(BaseModel):
    stage: ProcessStage
    hrt_ratio: float = Field(
        default=1.0,
        ge=0.25,    # Greater than or Equal: 0.25 미만 거부
        le=2.5,     # Less than or Equal: 2.5 초과 거부
        description="HRT 비율 (1.0 = 설계값 100%)",
    )

API 요청 시 자동 적용: