헤더 파라미터
헤더 파라미터 (Header Parameters)
헤더(header) 파라미터는 Query, Path, Cookie 파라미터를 정의하는 것과 똑같은 방식으로 정의할 수 있어요.
출처: 공식문서
Header 임포트하기 (Import Header)
먼저 Header를 임포트해요:
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
return {"User-Agent": user_agent}
파이썬 3.10+ -
Annotated를 안 쓰는 버전: 가능하면Annotated버전을 쓰는 걸 권해요.from fastapi import FastAPI, Header app = FastAPI() @app.get("/items/") async def read_items(user_agent: str | None = Header(default=None)): return {"User-Agent": user_agent}
헤더 파라미터 선언하기 (Declare Header parameters)
Path, Query, Cookie와 같은 구조로 헤더 파라미터를 선언하면 돼요. 기본값뿐 아니라 모든 추가 검증·주석 파라미터도 지정할 수 있어요:
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
return {"User-Agent": user_agent}
파이썬 3.10+ -
Annotated를 안 쓰는 버전:from fastapi import FastAPI, Header app = FastAPI() @app.get("/items/") async def read_items(user_agent: str | None = Header(default=None)): return {"User-Agent": user_agent}
기술적 세부사항:
Header는Path,Query,Cookie의 "자매" 클래스예요. 같은 공통Param클래스를 상속해요. 다만fastapi에서Query,Path,Header등을 import하면 그것들은 사실 특별한 클래스를 반환하는 함수라는 걸 기억하세요.헤더를 선언할 때는 반드시
Header를 써야 해요. 그렇지 않으면 파라미터가 쿼리 파라미터로 해석되거든요.
자동 변환 (Automatic conversion)
Header에는 Path, Query, Cookie가 제공하는 것 위에 작은 추가 기능이 하나 있어요.
대부분의 표준 헤더는 "하이픈" 문자(마이너스 기호, -)로 구분돼요. 그런데 user-agent 같은 변수명은 Python에서 유효하지 않아요.
그래서 기본적으로 Header는 파라미터 이름의 문자를 밑줄(_)에서 하이픈(-)으로 변환해서 헤더를 추출하고 문서화해요. 또 HTTP 헤더는 대소문자를 구분하지 않으니, 파이썬 표준 스타일("snake_case")로 선언해도 돼요. 그래서 User_Agent처럼 첫 글자를 대문자로 바꿔야 할 필요 없이 Python에서 평소처럼 user_agent를 쓰면 되는 거예요.
만약 특정한 이유로 밑줄→하이픈 자동 변환을 끄고 싶다면, Header의 convert_underscores 파라미터를 False로 설정하면 돼요:
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(
strange_header: Annotated[str | None, Header(convert_underscores=False)] = None,
):
return {"strange_header": strange_header}
파이썬 3.10+ -
Annotated를 안 쓰는 버전:from fastapi import FastAPI, Header app = FastAPI() @app.get("/items/") async def read_items( strange_header: str | None = Header(default=None, convert_underscores=False), ): return {"strange_header": strange_header}
convert_underscores를 False로 설정하기 전에 명심할 점이 있어요. 일부 HTTP 프록시와 서버는 밑줄이 포함된 헤더 사용을 허용하지 않아요.
중복 헤더 (Duplicate headers)
재미있는 건, 같은 이름의 헤더가 여러 개 올 수 있다는 거예요. 예를 들어 X-Token 헤더가 두 번 오는 경우죠. 이때 타입을 list로 선언하면 여러 값을 받을 수 있어요:
from typing import Annotated
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/items/")
async def read_items(x_token: Annotated[list[str] | None, Header()] = None):
return {"X-Token values": x_token}
파이썬 3.10+ -
Annotated를 안 쓰는 버전:from fastapi import FastAPI, Header app = FastAPI() @app.get("/items/") async def read_items(x_token: list[str] | None = Header(default=None)): return {"X-Token values": x_token}
리스트로 선언하면 두 번 온 X-Token 값이 리스트로 묶여서 전달돼요.
요약 (Recap)
헤더는 Header로 선언하고, 패턴은 Query, Path, Cookie와 똑같아요. 그리고 변수명의 밑줄은 걱정하지 마세요. FastAPI가 자동으로 변환해 주니까요.