[fastapi] 문자열 검증(String Validation) 이해하기

1. FastAPI와 Pydantic의 검증 기능

FastAPI는 데이터 검증을 위해 Pydantic을 활용한다. Pydantic은 파이썬 데이터 모델링 라이브러리로, 입력 데이터의 유효성을 검증하고, 오류를 관리하는 데 최적화되어 있다. FastAPI는 이를 바탕으로 사용자가 입력한 문자열 데이터가 올바른 형식과 조건을 충족하는지 쉽게 확인할 수 있게 한다.

2. `Query`를 사용한 기본 문자열 검증

FastAPI에서 문자열 검증을 가장 쉽게 수행할 수 있는 방법은 Query 클래스를 사용하는 것이다. Query는 쿼리 매개변수에 대한 다양한 검증 조건을 설정할 수 있는 유용한 도구이다.

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(name: str = Query(..., min_length=3, max_length=50)):
    return {"name": name}

위 예제에서 name 매개변수는 최소 길이 3, 최대 길이 50의 문자열이어야 한다. 만약 이 조건을 충족하지 않으면 FastAPI는 자동으로 422 Unprocessable Entity 응답을 반환하며, 유효하지 않은 입력에 대한 오류 메시지를 제공한다.

3. 정규 표현식을 활용한 고급 문자열 검증

정규 표현식(Regular Expression)을 사용하면, 문자열이 특정 패턴을 따르는지 검증할 수 있다. FastAPI는 Query의 regex 매개변수를 통해 정규 표현식을 사용할 수 있도록 지원한다.

@app.get("/users/")
async def read_user(username: str = Query(..., regex="^[a-zA-Z0-9_]+$")):
    return {"username": username}

이 예제에서 username 매개변수는 영문 대소문자, 숫자, 언더스코어(_)만 포함할 수 있다. 정규 표현식 ^[a-zA-Z0-9_]+$는 문자열이 이러한 문자들로만 구성되었는지 확인한다. 조건에 맞지 않는 문자열이 입력되면, FastAPI는 마찬가지로 422 에러를 반환한다.

4. 선택적 문자열 검증

때로는 문자열 매개변수가 선택적일 수 있으며, 이 경우 기본값으로 None을 설정하거나 Optional 타입을 사용할 수 있습니다.

from typing import Optional

@app.get("/search/")
async def search_items(query: Optional[str] = Query(None, min_length=3, max_length=50)):
    return {"query": query}

이 경우 query 매개변수는 선택 사항이며, 입력되지 않으면 None 값을 가진다. 그러나 입력된 경우에는 최소 및 최대 길이 조건을 검증한다.

즉, 실행결과는 아래와 같다.

# 오류 
GET http://localhost:8000/search 
GET http://localhost:8000/search?query=ab 

# 정상
GET http://localhost:8000/search?query=abc

5. Pydantic 모델을 통한 고급 문자열 검증

FastAPI에서는 쿼리 매개변수뿐만 아니라 요청 본문에 대한 검증도 수행할 수 있다. Pydantic 모델을 정의하여, 더 복잡한 문자열 검증을 포함한 다양한 데이터 검증을 수행할 수 있다.

from pydantic import BaseModel, validator

class Item(BaseModel):
    name: str

    @validator("name")
    def validate_name(cls, value):
        if len(value) < 3 or len(value) > 50:
            raise ValueError("Name must be between 3 and 50 characters")
        if not value.isalnum():
            raise ValueError("Name must contain only alphanumeric characters")
        return value

@app.post("/items/")
async def create_item(item: Item):
    return item

위의 코드에서는 name 필드에 대해 사용자 정의 검증 함수인 validate_name을 사용하여 문자열 길이와 알파벳 및 숫자만 포함하는지를 검증한다. 조건에 맞지 않으면 ValueError를 발생시키고, FastAPI는 이 오류를 클라이언트에게 전달한다.

6. 검증 오류 처리 및 사용자 정의 응답

FastAPI는 검증 오류 발생 시 자동으로 JSON 형식의 오류 응답을 생성한다. 이를 통해 클라이언트는 어떤 필드가 잘못되었는지, 그리고 그 이유를 쉽게 알 수 있다. 또한, 검증 오류를 처리하여 사용자 정의 응답을 제공할 수도 있다.

from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi import Request
from fastapi import FastAPI

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"message": "Validation error", "details": exc.errors()},
    )

위의 예제에서는 검증 오류가 발생했을 때, 사용자 정의 오류 메시지를 반환하도록 설정하였다.