Python 타입 힌트와 mypy로 런타임 에러 줄이기

문제 상황

재택근무 중 FastAPI 기반 백엔드를 운영하면서 타입 관련 에러가 잦았다. 특히 딕셔너리로 데이터를 주고받다 보니 키 오타나 타입 불일치로 인한 런타임 에러가 빈번했다.

def get_user_info(user_id):
    user = db.get_user(user_id)
    return {
        'name': user.name,
        'age': user.age
    }

# 다른 파일에서
info = get_user_info(123)
print(info['username'])  # KeyError 발생

타입 힌트 적용

Python 3.8부터 더 강력해진 타입 힌트를 본격적으로 도입했다. typing 모듈의 TypedDict를 활용하면 딕셔너리 구조도 명확히 정의할 수 있다.

from typing import TypedDict

class UserInfo(TypedDict):
    name: str
    age: int

def get_user_info(user_id: int) -> UserInfo:
    user = db.get_user(user_id)
    return {
        'name': user.name,
        'age': user.age
    }

mypy 설정

프로젝트에 mypy를 추가하고 CI에 포함시켰다.

# mypy.ini
[mypy]
python_version = 3.8
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True

VSCode에서도 Pylance를 활성화해 실시간으로 타입 오류를 확인할 수 있도록 했다.

결과

도입 후 3주간 타입 관련 버그가 70% 정도 줄었다. 특히 함수 인터페이스가 명확해지면서 협업할 때 커뮤니케이션 비용도 감소했다. 초기 타입 정의 작성 시간이 추가되지만, 디버깅 시간 단축으로 충분히 보상됐다.

Pydantic과 함께 사용하면 더 강력하지만, 일단은 표준 라이브러리 수준에서 충분히 효과를 봤다.