특강

[FastAPI 2일차] FastAPI에서 타입 힌트(Type Hint)의 목적과 활용법 완전 정리 1/2 (250528)

Chansman 2025. 5. 28. 18:37

🧠 FastAPI에서 타입 힌트(Type Hint)의 목적과 활용법 완전 정리

타입 힌트는 단순한 문법 요소가 아닙니다. FastAPI에서는 가독성 향상, 문서 자동화, 유효성 검사 등 다양한 측면에서 핵심적인 역할을 합니다. 본 글에서는 스크립트 기반 수업 내용을 바탕으로 타입 힌트의 개념, 작성법, FastAPI와의 실전 활용법까지 단계별로 정리합니다.

1. 🔍 타입 힌트의 목적과 사용법

  • 타입 힌트는 **사람(개발자)**을 위한 것입니다. 파이썬 인터프리터는 이를 무시하지만, 읽는 사람은 변수가 어떤 타입을 가지는지 쉽게 이해할 수 있습니다.
  • 예시:
    • : 뒤에 타입을 명시
    • 이는 '문서화' 목적이며, 타입 강제는 아닙니다.
  • age: int = 25 name: str = "Alice"
  • FastAPI에서는 이 정보가 Swagger UI 문서 생성에도 사용됩니다.

2. 🐍 파이썬의 타입 시스템과 메모리 관리

  • 대부분의 정적 타입 언어(C, Java 등)는 변수 선언 시 메모리 공간을 확보하기 위해 타입을 명시해야 합니다.
  • 그러나 파이썬은 동적 타입 언어로, 실행 시점에 메모리를 알아서 조절합니다.

➡️ 따라서 파이썬에서의 타입 힌트는 런타임에 영향을 주지 않으며, 가독성 및 협업을 위한 도구입니다.

3. 📊 타입 힌트 기본 작성법

✅ 원시 타입

age: int = 30
name: str = "Alice"
is_active: bool = True

✅ 복합 타입 (List, Dict 등)

from typing import List, Dict, Union

fruits: List[str] = ["apple", "banana"]
scores: List[int] = [90, 85]
user: Dict[str, Union[str, int]] = {"name": "Alice", "age": 30}
  • Union: 여러 타입을 허용할 때 사용.

✅ 함수에 적용

def greet(name: str) -> str:
    return f"Hello {name}"

def print_name(name: str) -> None:
    print(name)
  • -> None은 반환값이 없음을 의미합니다.

4. 📚 Iterable, 딕셔너리 순회와 함수 적용

✅ 반복 가능한 인자 처리

from typing import Iterable

def print_names(names: Iterable[str]) -> None:
    for name in names:
        print(name)

✅ 딕셔너리 타입 힌트

user_info: Dict[str, Union[str, int]] = {"name": "Charlie", "age": 20}
  • user_info.keys() → 키만 순회
  • user_info.values() → 값만 순회
  • user_info.items() → 키와 값 쌍으로 순회

5. 🔍 FastAPI에서 타입 힌트 + 데이터 유효성 검사

타입 힌트는 FastAPI에서 다음 기능과 연결됩니다:

  • ✅ Swagger 문서 자동 생성
  • ✅ 쿼리/경로/바디 파라미터 유효성 검사
  • ✅ API 동작의 신뢰성과 명확성 보장

✅ 쿼리 파라미터 예제

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def read_items(max_price: int = Query(gt=99, lt=1000)):
    return {"max_price": max_price}
  • gt, lt는 각각 초과/미만 조건 지정
  • 이 조건을 만족하지 않으면 자동으로 422 에러 반환

✅ 디폴트 값 설정

@app.get("/items")
def read_items(max_price: int = Query(default=100, gt=99)):
    return {"max_price": max_price}
  • 쿼리 파라미터 생략 시 기본값 사용

✅ 핵심 요약

항목 설명

🎯 타입 힌트 목적 코드 가독성, 협업 효율, 문서 자동화
⚙️ 런타임 영향 없음 (사람을 위한 정보)
🔧 적용 대상 변수, 함수 인자 및 반환값, API 요청/응답
🚀 FastAPI 활용 문서 생성, 유효성 검사, 안정성 향상

💡 실무 팁

  • Pydantic 모델과 함께 사용하면 복잡한 데이터 구조도 타입으로 선언 가능
  • typing 모듈의 Optional, Literal, Annotated 등 고급 기능도 활용해 보세요
  • 타입 힌트를 생략하면 문서 자동화 및 검증이 제한되므로 가능한 한 적극적으로 작성하는 습관을 들이세요

타입 힌트는 FastAPI에서 단순한 문법 장식이 아닌, 강력한 협업 도구이자 API 품질을 좌우하는 핵심 요소입니다 ✅