📬 Header Parameter

FastAPI에서 Header 파라미터는 단순히 “요청 정보”를 읽는 기능이 아니다.

Header는 요청의 맥락(Context)과 요청자의 정체성을 담는 핵심 통로다.

이번 글에서는 Header가 무엇인지, 왜 필요한지, FastAPI에서 어떤 개념으로 다뤄지는지를 천천히 구조적으로 정리한다.

---

📚 어원으로 이해하기

Header는 영어로 머리 라는 뜻이다.

HTTP 메시지도 사람처럼 구조를 가진다.

구성 요소	의미	사람에 비유하면
Header	요청의 메타 정보	머리 (판단, 정체성)
Body	실제 전달 데이터	몸통 (내용물)

즉, Header는 “이 요청이 어떤 상황에서 왔는지”를 설명한다.

---

✉️ 편지로 비유하면

HTTP 요청을 편지로 생각해보자.

편지 요소	HTTP 요청
봉투에 적힌 정보	Header
편지 내용	Body
받는 사람 주소	Host 헤더
보낸 사람 정보	User-Agent 헤더

봉투 정보가 없으면 편지는 어디서 왔는지, 어디로 가야 하는지 알 수 없다.

HTTP 요청도 마찬가지다.

---

🧭 Header에는 어떤 정보가 들어갈까?

Header에는 데이터 자체가 아니라 데이터를 설명하는 정보가 담긴다.

헤더 예시	의미
User-Agent	요청을 보낸 클라이언트 정보
Authorization	인증 토큰
Content-Type	Body 데이터 형식
Accept	원하는 응답 타입

FastAPI는 이 Header 값들을 함수 파라미터처럼 직접 받아서 사용할 수 있게 해준다.

---

🚀 FastAPI에서 Header의 역할

FastAPI에서 Header는 Query, Path, Cookie와 같은 “파라미터 출처” 중 하나다.

파라미터 종류	위치	비유
Path	URL 경로	배송지 주소
Query	?key=value	요청 옵션
Header	요청 헤더	봉투 정보
Body	요청 본문	상자 안 내용물

---

🧪 직접 체험해보기

이제 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}

이 코드의 의미를 한 줄로 읽으면 다음과 같다.

결과:

{"User-Agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"}

브라우저가 자동으로 보내는 User-Agent 헤더 값이 그대로 출력 된다.

🔍 여기서 중요한 관찰 포인트

• user_agent는 함수의 일반 파라미터처럼 보인다
• 하지만 Query 파라미터가 아니다
• Header()를 명시했기 때문에 Header에서 값을 가져온다

FastAPI는 Header()를 보는 순간 이 파라미터를 Header 전용으로 해석한다.

---

🔄 자동 변환 기능 (Underscore ↔ Hyphen)

Header 파라미터에는 Query, Path에는 없는 아주 중요한 자동 변환 규칙이 하나 있다.

바로 언더스코어(_) → 하이픈(-) 자동 변환이다.

---

❓ 왜 이런 기능이 필요할까?

HTTP Header 이름은 하이픈(-)을 사용하는 것이 표준이다.

• User-Agent
• Content-Type
• Accept-Language

하지만 Python 변수명에는 하이픈을 사용할 수 없다.

# ❌ 문법 오류 user-agent = "Mozilla" 

그래서 FastAPI는 Python 친화적인 이름을 쓰면 HTTP 표준 Header 이름으로 자동 변환해준다.

🔁 자동 변환 규칙

Python 변수명	실제 찾는 Header
user_agent	User-Agent
content_type	Content-Type
x_token	X-Token

---

📌 실제 코드에서 어떻게 동작할까?

@app.get("/items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
    return {"User-Agent": user_agent}

이 코드는 내부적으로 이렇게 해석된다.

---

🔕 자동 변환을 끄고 싶다면?

아주 특수한 상황에서는 언더스코어가 포함된 Header 이름을 그대로 써야 할 수도 있다.

이럴 때 사용하는 옵션이 convert_underscores=False다.

@app.get("/items/")
async def read_items(
    strange_header: Annotated[str | None, Header(convert_underscores=False)] = None
):
    return {"strange_header": strange_header}

이 경우 FastAPI는

• strange-header ❌
• strange_header ⭕

를 그대로 찾는다.

특별한 이유가 없다면 기본 설정(자동 변환 ON)을 유지하는 것이 안전하다.

---

📦 필수 Header vs 선택 Header

✔️ 선택 Header

기본값이 있으면 해당 Header는 선택이다.

user_agent: Annotated[str | None, Header()] = None 

• Header 없어도 OK
• 값이 없으면 None

---

❗ 필수 Header

기본값을 제거하면 필수 Header가 된다.

@app.get("/secure/")
async def secure_endpoint(authorization: Annotated[str, Header()]):
    return {"token": authorization}

Authorization Header 없이 요청하면

• FastAPI가 자동으로 422 에러 반환
• 직접 검사 코드 작성할 필요 없음

---

📚 중복 Header 처리 (list 타입)

같은 Header가 여러 번 전달되는 경우도 있다.

이때는 list 타입으로 선언하면 된다.

@app.get("/items/")
async def read_items(x_token: Annotated[list[str] | None, Header()] = None):
    return {"X-Token values": x_token}

요청이 이렇게 오면

X-Token: foo X-Token: bar 

응답은 이렇게 된다.

{ "X-Token values": ["bar", "foo"] } 

---

🧩 Header 파라미터 선언 패턴 정리

FastAPI의 파라미터들은 모두 동일한 패턴을 따른다.

종류	선언 형태
Query	Annotated[str, Query()]
Path	Annotated[str, Path()]
Header	Annotated[str, Header()]
Cookie	Annotated[str, Cookie()]

---

🧠 전체 개념 요약

개념	핵심 의미
Header	요청의 맥락과 정체성
역할	인증, 환경, 요청 조건 전달
선언 방식	Annotated + Header()
자동 변환	_ → - 자동 처리
필수 여부	기본값 유무로 결정
중복 Header	list 타입으로 처리