쿠키 파라미터 모델

서로 관련된 쿠키들이 여러 개 있다면, Pydantic 모델로 한 번에 선언할 수 있어요. 🍪

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

참고: 이 기능은 FastAPI 버전 0.115.0부터 지원돼요. 🤓

이 기법은 Query, Cookie, Header 모두에 똑같이 적용돼요. 😎

출처: 공식문서

Pydantic 모델로 쿠키 선언하기 (Cookies with a Pydantic Model)

필요한 쿠키 파라미터를 Pydantic 모델에 선언하고, 그 파라미터를 Cookie로 선언하면 돼요:

from typing import Annotated

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Annotated[Cookies, Cookie()]):
    return cookies

파이썬 3.10+ - Annotated를 안 쓰는 버전: 가능하면 Annotated 버전을 쓰는 걸 권해요.

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Cookies(BaseModel):
    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Cookies = Cookie()):
    return cookies

FastAPI는 요청에서 받은 각 쿠키의 데이터를 필드별로 추출해서, 우리가 정의한 Pydantic 모델을 만들어 줘요. 즉 session_id, fatebook_tracker, googall_tracker 쿠키가 자동으로 모델의 해당 필드로 채워져요.

문서 확인하기 (Check the Docs)

/docs의 문서 UI에서 정의된 쿠키를 확인할 수 있어요.

주의: 브라우저가 쿠키를 특별하게, 그리고 뒤에서 조용히 처리하기 때문에 JavaScript로는 쿠키를 쉽게 건드리지 못해요. /docs의 API 문서 UI에서 path operation의 쿠키 문서를 볼 수는 있지만, 데이터를 채우고 "Execute"를 눌러도 문서 UI는 JavaScript 기반이라 쿠키가 전송되지 않아요. 그래서 값을 아무것도 안 적은 것처럼 오류 메시지를 보게 될 거예요.

추가 쿠키 금지하기 (Forbid Extra Cookies)

아마 흔하지는 않겠지만, 특별한 경우에 받고 싶은 쿠키를 제한하고 싶을 수 있어요. 이제 API가 자기만의 쿠키 동의(consent)를 제어할 수 있게 된 거죠. 🤪

Pydantic의 모델 설정으로 extra 필드를 forbid하면 돼요:

from typing import Annotated

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Annotated[Cookies, Cookie()]):
    return cookies

파이썬 3.10+ - Annotated를 안 쓰는 버전:

from fastapi import Cookie, FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    session_id: str
    fatebook_tracker: str | None = None
    googall_tracker: str | None = None


@app.get("/items/")
async def read_items(cookies: Cookies = Cookie()):
    return cookies

model_config = {"extra": "forbid"}를 넣으면, 모델에 선언되지 않은 쿠키가 오면 FastAPI가 오류를 내요. 즉 API가 받아들이는 쿠키의 목록을 정확히 통제할 수 있게 돼요.

더 알아보기 (Learn more)

공식문서: Cookie Parameter Models

쿠키 파라미터 모델