여기서 -> str의 의미:

“이 함수는 문자열을 반환한다”

📦 컬렉션 타입 힌트

리스트(list)

names: list[str] = ["철수", "영희", "민수"]

✔ 문자열만 들어가는 리스트
✔ IDE 자동완성이 정확해진다

딕셔너리(dict)

scores: dict[str, int] = {
    "철수": 90,
    "영희": 95
}

✔ key는 문자열
✔ value는 정수

튜플(tuple)

user: tuple[str, int, bool] = ("jay", 25, True)

✔ 위치마다 타입이 고정된다
✔ 구조가 명확해진다

🔀 선택적 값 (None 허용)

어떤 값은 있을 수도, 없을 수도 있다.

nickname: str | None = None

이 타입의 의미는 다음과 같다.

👉 문자열이거나
👉 아무 값도 없을 수 있다

Python 3.10 이상에서는 | 문법을 사용한다.

🔁 여러 타입 허용하기

user_id: str | int

✔ 문자열 ID 허용
✔ 숫자 ID도 허용

실무에서 매우 자주 등장하는 패턴

🧠 타입 힌트의 진짜 가치

• 자동완성 정확도 상승
• 실행 전 오류 탐지
• 코드 자체가 문서가 됨

❗ 타입 힌트는 “타입 체크용 기능”이 아니다
❗ 의사소통 도구다

🚀 FastAPI에서의 활용

이제 타입 힌트가 왜 “있으면 좋은 것”이 아니라
“없으면 안 되는 것”으로 바뀌는 순간을 보자.

👉 FastAPI는 타입 힌트를 읽어서 동작하는 프레임워크다

🔍 1. 데이터 검증 (Validation)

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

이 코드에서 핵심: user_id: int

• /users/123 → 정상 동작
• /users/abc → 자동으로 422 에러 반환

❌ 개발자가 if 문으로 검사하지 않는다
❌ try / except를 쓰지 않는다

✅ 타입 힌트 하나로 요청 데이터 검증이 끝난다

🔄 2. 자동 타입 변환

@app.get("/items/{item_id}")
def get_item(item_id: int):
    return {"item_id": item_id}    

URL의 모든 값은 기본적으로 문자열이다.

하지만 FastAPI는 이렇게 동작한다.

• "42" → int 42
• "3.14" → 변환 실패 → 에러

👉 타입 힌트는 변환 규칙이 된다

📄 3. API 문서 자동 생성

@app.get("/search")
def search(
    keyword: str,
    page: int = 1,
    limit: int | None = None
):
    return {
        "keyword": keyword,
        "page": page,
        "limit": limit
    }

서버 실행 후 /docs에 접속하면
놀라운 일이 벌어진다.

• 각 파라미터의 타입
• 필수 / 선택 여부
• 기본값

이 모든 것이 문서로 자동 생성된다.

✅ 타입 힌트 = API 스펙 문서

🧩 Request Body와 타입 힌트

FastAPI에서 JSON 요청 본문은
타입 힌트 없이는 제대로 다룰 수 없다.

from pydantic import BaseModel

class UserCreate(BaseModel):
    name: str
    age: int
    email: str | None = None

@app.post("/users")
def create_user(user: UserCreate):
    return user

여기서 벌어지는 일:

• 필수 필드 자동 검사
• 타입 불일치 자동 에러
• 문서 자동 생성

👉 타입 힌트 하나로
👉 검증 + 변환 + 문서가 동시에 해결된다

⚠️ 타입 힌트가 없으면 생기는 문제

• 요청 검증이 불가능하다
• 자동 문서가 부정확해진다
• IDE 자동완성이 무너진다

❗ FastAPI에서 타입 힌트는 선택이 아니다
❗ 설계 그 자체다

🧠 핵심 정리

• 타입 힌트는 실행을 위한 기능이 아니다
• 의도를 표현하는 언어다
• FastAPI는 그 의도를 코드로 바꿔준다

👉 타입 힌트를 잘 쓰면
👉 API 설계가 곧 코드가 된다

✨ 최종 요약

• 파이썬 단독 → 타입 힌트는 권장
• FastAPI → 타입 힌트는 필수
• 코드 = 문서 = 검증 규칙

🧠 “FastAPI에서 타입 힌트는 선택지가 아니라 언어다”