매개변수에 validation 제약 조건을 어떻게 추가합니까?

Question

Accepted Answer

타입 검사를 넘어, FastAPI는 `Query`, `Path`, `Field`를 사용해 경로/쿼리 매개변수와 모델 필드에 **제약 조건**을 추가할 수 있게 합니다. 길이, 범위, 패턴 같은 규칙을 강제하며, 위반 시 자동 422 오류와 문서화를 제공합니다. ## Query 및 Path 제약 조건 ```python from fastapi import Query, Path @app.get("/items") def search( q: str = Query(min_length=3, max_length=50), # 문자열 길이 범위 page: int = Query(default=1, ge=1), # >= 1 limit: int = Query(default=10, ge=1, le=100), # 1 <= limit <= 100 code: str = Query(pattern=r"^[A-Z]{3}$"), # 정규식 패턴 ): ... @app.get("/items/{item_id}") def get(item_id: int = Path(ge=1)): # 경로 매개변수는 >= 1 이어야 함 ... ``` `Query()`와 `Path()`는 쿼리 및 경로 매개변수에 제약 조건을 추가합니다. 일반적인 것들: `min_length`/`max_length`(문자열), `ge`/`gt`/`le`/`lt`(숫자), `pattern`(정규식). 위반 시 자동으로 명확한 422 오류가 발생합니다. ## Pydantic 모델의 Field 제약 조건 ```python from pydantic import BaseModel, Field, EmailStr class User(BaseModel): name: str = Field(min_length=1, max_length=100) age: int = Field(ge=0, le=120) email: EmailStr # 타입을 통한 형식 validation bio: str = Field(default="", max_length=500, description="User bio") ``` 동일한 제약 조건이 `Field()`를 통해 모델 필드에 적용되어 요청 본문을 검증합니다. 특수 타입(`EmailStr`, `HttpUrl`, `UUID`)은 형식을 검증합니다. ## 제약 조건은 문서도 풍부하게 만듭니다 ```python q: str = Query(min_length=3, description="Search query", example="phone") # 제약 조건 + 설명 + 예시가 자동 생성 API 문서에 나타납니다 ``` 선언하는 모든 제약 조건은 OpenAPI 문서에도 반영되어, 사용자가 규칙을 볼 수 있습니다. ## 왜 중요한가 validation 제약 조건을 추가하는 것은 **보안/견고성**과 좋은 API 설계 모두에 중요합니다. 규칙(길이 제한, 숫자 범위, 정규식 패턴, 형식 타입)을 선언하면 잘못된 형식이거나 악의적인 입력이 로직에 도달하기 *전에* 명확한 오류와 함께 거부되도록 보장합니다. 원시 입력을 절대 신뢰해서는 안 되므로 이것은 필수적입니다. FastAPI는 이를 선언적이고 손쉽게 만듭니다: `Query`/`Path`/`Field` 제약 조건은 자동으로 검증되고(구조화된 422 오류 생성) 동시에 API 문서에 문서화되므로, 규칙이 단일 선언으로부터 강제되고 전달됩니다. 일반적인 제약 조건과 특수 validation 타입을 아는 것은 안전하고 잘 정의된 엔드포인트를 구축하기 위한 일상 지식입니다. 기본 타입 검사를 넘어 데이터가 충족해야 하는 실제 비즈니스 규칙을 강제하는 방법입니다.