헤더 파라미터 모델

헤더 파라미터 모델 (Header Parameter Models)

관련된 헤더 파라미터들이 여러 개 있다면, Pydantic 모델을 만들어 한 번에 선언할 수 있습니다.

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

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

출처: 공식문서

Pydantic 모델로 헤더 파라미터 선언하기 (Header Parameters with a Pydantic Model)

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

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()

class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []

@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

🤓 다른 버전과 변형

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

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()

class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []

@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
    return headers

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

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

/docs의 문서 UI에서 필수 헤더들을 확인할 수 있습니다.

추가 헤더 금지하기 (Forbid Extra Headers)

몇몇 특수한 경우(아마 흔하지는 않겠지만)에는 받고 싶은 헤더만 제한하고 싶을 수 있어요.

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

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()

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

    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []

@app.get("/items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

🤓 다른 버전과 변형

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

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()

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

    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []

@app.get("/items/")
async def read_items(headers: CommonHeaders = Header()):
    return headers

클라이언트가 추가 헤더를 보내려고 하면 오류 응답을 받게 됩니다.

예를 들어 클라이언트가 값이 plumbus인 tool 헤더를 보내려고 하면, 헤더 파라미터 tool은 허용되지 않는다는 오류 응답을 받게 됩니다:

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

밑줄(언더스코어) 변환 비활성화하기 (Disable Convert Underscores)

일반적인 헤더 파라미터와 마찬가지로, 파라미터 이름에 밑줄 문자가 있으면 자동으로 하이픈으로 변환됩니다.

예를 들어 코드에서 save_data라는 헤더 파라미터를 만들면, 예상되는 HTTP 헤더는 save-data가 되고, 문서에도 그렇게 표시됩니다.

어떤 이유로든 이 자동 변환을 비활성화해야 한다면, 헤더 파라미터용 Pydantic 모델에서도 그렇게 할 수 있습니다.

from typing import Annotated

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()

class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []

@app.get("/items/")
async def read_items(
    headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
):
    return headers

🤓 다른 버전과 변형

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

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()

class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []

@app.get("/items/")
async def read_items(headers: CommonHeaders = Header(convert_underscores=False)):
    return headers

!!! warning "경고" convert_underscores를 False로 설정하기 전에, 일부 HTTP 프록시와 서버는 밑줄이 있는 헤더 사용을 허용하지 않는다는 점을 명심하세요.

요약 (Summary)

FastAPI에서 헤더를 선언할 때 Pydantic 모델을 사용할 수 있습니다. 😎

더 알아보기 (Learn more)

• 관련 헤더 파라미터들을 Pydantic 모델로 묶어 재사용하고, 검증과 메타데이터를 한 번에 선언하세요.
• model_config = {"extra": "forbid"}로 예상 밖의 헤더를 거부할 수 있습니다.
• 헤더 이름의 밑줄은 기본적으로 하이픈으로 변환되며, convert_underscores=False로 끌 수 있습니다.