쿼리 파라미터 모델

쿼리 파라미터 모델 (Query Parameter Models)

서로 관련된 쿼리 파라미터들이 있다면, Pydantic 모델을 만들어 한 번에 선언할 수 있습니다.

이렇게 하면 그 모델을 여러 곳에서 재사용할 수 있고, 모든 파라미터에 대한 검증(validation)과 메타데이터를 한꺼번에 선언할 수 있어요. 😎

!!! note "참고" 이 기능은 FastAPI 버전 0.115.0부터 지원됩니다. 🤓

출처: 공식문서

Pydantic 모델로 쿼리 파라미터 선언하기 (Query Parameters with a Pydantic Model)

필요한 쿼리 파라미터들을 Pydantic 모델로 선언하고, 그다음 파라미터를 Query로 선언하세요:

from typing import Annotated, Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query

🤓 다른 버전과 변형

!!! tip "팁" 가능하다면 Annotated 버전을 사용하는 걸 권장합니다.

from typing import Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: FilterParams = Query()):
    return filter_query

FastAPI는 요청의 쿼리 파라미터에서 필드별로 데이터를 추출해서, 여러분이 정의한 Pydantic 모델을 돌려줍니다.

문서에서 확인하기 (Check the Docs)

/docs의 문서 UI에서 쿼리 파라미터들을 확인할 수 있습니다.

추가 쿼리 파라미터 금지하기 (Forbid Extra Query Parameters)

몇몇 특수한 경우(아마 흔하지는 않겠지만)에는 받고 싶은 쿼리 파라미터만 제한하고 싶을 수 있어요.

Pydantic 모델 설정을 사용해서 extra 필드를 forbid할 수 있습니다:

from typing import Annotated, Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    model_config = {"extra": "forbid"}

    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query

🤓 다른 버전과 변형

!!! tip "팁" 가능하다면 Annotated 버전을 사용하는 걸 권장합니다.

from typing import Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    model_config = {"extra": "forbid"}

    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: FilterParams = Query()):
    return filter_query

클라이언트가 쿼리 파라미터에 추가 데이터를 보내려고 하면 오류 응답을 받게 됩니다.

예를 들어 클라이언트가 값이 plumbus인 tool 쿼리 파라미터를 보내려고 하면, 이런 식입니다:

https://example.com/items/?limit=10&tool=plumbus

쿼리 파라미터 tool은 허용되지 않는다는 오류 응답을 받게 됩니다:

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["query", "tool"],
            "msg": "Extra inputs are not permitted",
            "input": "plumbus"
        }
    ]
}

요약 (Summary)

FastAPI에서 쿼리 파라미터를 선언할 때 Pydantic 모델을 사용할 수 있습니다. 😎

!!! tip "팁" 스포일러 주의: Pydantic 모델로 쿠키와 헤더도 선언할 수 있는데, 그것에 대해서는 튜토리얼 후반부에서 배우게 될 거예요. 🤫

더 알아보기 (Learn more)

• 관련 쿼리 파라미터들을 Pydantic 모델로 묶어 재사용하고, 검증(Field(gt=0, le=100) 등)과 메타데이터를 한 번에 선언하세요.
• model_config = {"extra": "forbid"}로 예상 밖의 쿼리 파라미터를 거부할 수 있습니다.
• 같은 패턴을 쿠키와 헤더에도 적용할 수 있습니다(튜토리얼 후반부 참고).