# Field-Level Validators (v2)
`@field_validator`를 사용한 개별 필드 검증입니다.
---
## 완전한 코드
```python
from pydantic import BaseModel, Field, field_validator
from typing import Optional
from datetime import datetime
class UserProfile(BaseModel):
"""사용자 프로필 (Pydantic v2)"""
username: str = Field(..., min_length=3, max_length=20, description="사용자명")
email: str = Field(..., description="이메일 주소")
age: int = Field(..., ge=0, le=150, description="나이")
bio: Optional[str] = Field(None, max_length=500, description="자기소개")
created_at: datetime = Field(default_factory=datetime.now)
@field_validator("username")
@classmethod
def validate_username(cls, v):
"""username은 영문자, 숫자, 언더스코어만 허용"""
if not v.replace("_", "").isalnum():
raise ValueError("username은 영문자, 숫자, 언더스코어만 가능합니다")
return v.lower()
@field_validator("email")
@classmethod
def validate_email(cls, v):
"""기본 이메일 검증"""
if "@" not in v or "." not in v.split("@")[1]:
raise ValueError("유효한 이메일 형식이 아닙니다")
return v.lower()
@field_validator("age")
@classmethod
def validate_age(cls, v):
"""나이 범위 검증"""
if v < 13:
raise ValueError("13세 이상만 가입 가능합니다")
return v
# 사용 예시
try:
user = UserProfile(
username="john_doe",
email="
[email protected]", # 자동으로 소문자 변환
age=25,
bio="안녕하세요"
)
print("✓ 검증 성공:", user)
print(" - username 소문자 변환:", user.username)
print(" - email 소문자 변환:", user.email)
except ValueError as e:
print("✗ 검증 실패:", e)
```
---
## 단계별 설명
### 1단계: 데코레이터 적용
```python
@field_validator("username") # 어떤 필드를 검증할지 지정
@classmethod
def validate_username(cls, v): # v는 해당 필드의 값
# 검증 로직
return v # 검증된 값 반환 (또는 수정된 값)
```
### 2단계: 실행 순서
1. **타입 강제 변환** — `int`, `str` 등으로 자동 변환
2. **`@field_validator` 실행** — 개별 필드 검증
3. **`@model_validator(mode="after")` 실행** — 모델 전체 검증
### 3단계: 값 변환
검증 함수에서 값을 수정해서 반환 가능:
```python
return v.lower() # 소문자로 정규화
return v.strip() # 공백 제거
return int(v) # 타입 변환
```
---
## 핵심 개념
| 항목 | 설명 |
|------|------|
| **`@field_validator`** | 단일 필드를 검증하는 데코레이터 |
| **`v` 파라미터** | 검증할 필드의 값 |
| **`cls` 파라미터** | 모델 클래스 (고정, @classmethod 필수) |
| **반환값** | 검증된 값 (수정 가능) |
---
## 다음 단계
[[codes/data-validation/pydantic/samples/model-validators|모델 전체 검증 - 여러 필드 간의 상호 검증]]