🏷️ Python Annotated 쉽게 이해하기

Annotated는 처음 보면 낯설다.
문법도 생소하고, 없어도 코드가 잘 돌아간다.

“타입 힌트만 써도 되는 거 아닌가?”
“이걸 왜 굳이 써야 하지?”

---

🤔 Annotated는 왜 등장했을까?

핵심부터 말하면 Annotated는
타입을 바꾸는 기능이 아니다.

---

📘 Annotate의 의미부터 이해

Annotate는 영어로 “주석을 달다, 메모를 남기다”라는 뜻.

책을 읽을 때를 떠올려보자.

• 중요한 문장에 밑줄을 긋고
• 옆에 메모를 남긴다
• 나중에 다시 봤을 때 빠르게 이해한다

Python의 Annotated는
바로 이 “메모”를 타입에 붙이는 도구다.

---

📦 택배 상자로 이해하는 Annotated

기본 택배 (타입만 있는 경우)

name: str = "jay"

┌─────────────────┐
│  📦 상자         │
│  타입: str       │
│  내용: "jay"     │
└─────────────────┘

이 상자는
“문자열이 들어 있다”는 것만 알려준다.

---

🏷️ 스티커가 붙은 택배 (Annotated 사용)

from typing import Annotated

name: Annotated[str, "이름은 50자 이하"] = "jay"

┌─────────────────┐
│    📦 상자       │
│  타입: str       │
│  내용: "jay"     │
├─────────────────┤
│ 🏷️ 스티커         │
│ "이름은 50자 이하" │
└─────────────────┘

상자 안의 내용은 바뀌지 않았다.
대신, 상자에 설명 스티커가 붙었다.

---

🧠 핵심 포인트

• Annotated는 타입을 유지한다
• 타입 옆에 추가 정보를 붙인다
• Python 자체는 이 정보를 무시한다
• FastAPI 같은 프레임워크가 이 정보를 읽어 활용한다

---

🔍 Annotated 문법을 단계별로 뜯어보기

1단계: 가장 기본 형태

from typing import Annotated

age: Annotated[int, "나이는 0 이상"] = 25

구성 요소	의미
age	변수 이름
Annotated[...]	추가 정보가 붙은 타입
int	실제 타입
"나이는 0 이상"	메모(스티커)
= 25	기본값

---

2단계: None 허용하기

# 문자열만 허용
name: Annotated[str, "이름"] = "jay"

# 문자열 또는 None
name: Annotated[str | None, "이름"] = None

이 패턴은
선택 입력값에서 아주 자주 등장한다.

---

🔗 FastAPI에서 Annotated가 빛나는 순간

FastAPI에서는
Annotated의 “스티커 자리”에
Query, Path, Header 같은 객체가 들어간다.

Query와 함께 사용하기

from typing import Annotated
from fastapi import Query

q: Annotated[str | None, Query(max_length=50)] = None

이 코드를 읽어보면,

q는 문자열이거나 None이고,
Query 검증으로 최대 50자까지 허용하며,
기본값은 None이다

---

⚖️ Annotated 이전 방식과 비교

❌ 예전 방식

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, max_length=50)
):
    return {"q": q}

문제점:

• 기본값과 검증 규칙이 섞여 있다
• 한눈에 읽기 어렵다

---

✅ Annotated 방식 (권장)

@app.get("/items/")
async def read_items(
    q: Annotated[str | None, Query(max_length=50)] = None
):
    return {"q": q}

---

🧩 구조 한 번에 정리하기

q: Annotated[str | None, Query(max_length=50)] = None
│  │           │                 │              │
│  │           │                 │              └─ 기본값
│  │           │                 └─ 검증 규칙 (스티커)
│  │           └─ 실제 타입
│  └─ Annotated 선언
└─ 변수명

---

📌 Annotated 정리

개념	의미
Annotated	타입에 메타 정보를 붙이는 도구
첫 번째 인자	실제 타입
두 번째 인자	추가 정보 (Query, Path 등)
기본값	= 로 별도 지정

---

🧠 꼭 암기할 필요는 없다

처음부터 완벽히 이해하려 하지 말고,

그리고 필요한 옵션은 그때그때 찾아서 붙이자.

---

✨ 마무리 한 줄 요약

• Annotated는 타입을 바꾸지 않는다
• 타입에 설명과 규칙을 붙인다
• FastAPI는 이 설명을 읽고 자동으로 동작한다