Pydantic에서 커스텀 validation을 어떻게 작성합니까?

Question

Accepted Answer

내장 제약 조건을 넘어, Pydantic은 필드 validator(필드 하나 검증)와 모델 validator(여러 필드에 걸쳐 검증)로 **커스텀 validation 로직**을 작성할 수 있게 합니다. 단순 제약 조건으로 표현할 수 없는 규칙을 위한 것입니다. (보여지는 구문은 Pydantic v2입니다.)

## 필드 validator — 단일 필드 검증/변환

```python
from pydantic import BaseModel, field_validator

class User(BaseModel):
    username: str
    password: str

@field_validator("username")
    @classmethod
    def username_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError("username must be alphanumeric")   # → 422 오류
        return v.lower()                                         # 값을 변환할 수도 있음
```

`@field_validator`는 필드에 커스텀 로직을 실행합니다: 유효하지 않은 입력을 거부하려면 `ValueError`를 발생시키고(FastAPI가 명확한 422로 변환), 변환된 값을 반환할 수도 있습니다(예: 소문자로 정규화).

## 모델 validator — 교차 필드 validation

```python
from pydantic import model_validator

class SignupForm(BaseModel):
    password: str
    confirm_password: str

@model_validator(mode="after")
    def passwords_match(self):
        if self.password != self.confirm_password:    # 여러 필드 비교
            raise ValueError("passwords do not match")
        return self
```

`@model_validator(mode="after")`는 모든 필드가 검증된 후, 전체 모델에 접근하여 실행됩니다. **여러 필드**가 관여하는 규칙(예: 비밀번호 일치 확인, 시작일이 종료일보다 앞서는지)에 사용됩니다.

## 내장 validation으로 먼저 충분한 경우가 많습니다

```python
class Product(BaseModel):
    price: float = Field(gt=0)          # 단순 규칙에는 Field 제약 조건 사용
    sku: str = Field(pattern=r"^[A-Z]{3}-\d+$")
    email: EmailStr                      # 형식에는 특수 타입
# 제약 조건/타입으로 규칙을 표현할 수 없을 때만 커스텀 validator 사용
```

단순 규칙에는 `Field` 제약 조건과 특수 타입을 우선하고, 진정한 비즈니스 로직에는 커스텀 validator를 사용하세요.

## 왜 중요한가

커스텀 Pydantic validation은 단순 타입 검사와 제약 조건을 넘어서는 비즈니스 규칙을 강제하는 데 중요합니다. validation은 **보안과 데이터 무결성**에 핵심적이므로, 어떤 규칙이든 표현할 수 있는 능력은 가치가 있습니다. **필드 validator**는 단일 필드 로직(커스텀 형식 검사, 정규화/변환)을 처리하고, **모델 validator**는 필드 수준 규칙으로는 표현할 수 없는 흔한 필요인 **교차 필드 validation**(비밀번호 일치, 날짜 범위, 조건부 필수)을 처리합니다.

validator는 FastAPI와 매끄럽게 통합됩니다. 발생한 `ValueError`는 자동으로 명확한 422 응답이 됩니다.

내장 제약 조건/타입을 언제 사용하고(단순 규칙) 커스텀 validator를 언제 사용하는지(실제 비즈니스 로직), 그리고 필드 validator와 모델 validator가 어떻게 다른지 이해하면, 들어오는 데이터가 애플리케이션의 요구사항을 완전히 충족하도록 보장할 수 있습니다. 견고하고 정확한 API를 구축하기 위한 중요한 지식입니다.