타입 힌트를 도입했는데 디버깅이 빨라졌다: 파이썬에서 “조사 속도”를 올리는 고정점들

thumbnail

타입 힌트를 도입했는데 디버깅이 빨라졌다: 파이썬에서 “조사 속도”를 올리는 고정점들

그날은 로그가 있었다. 경고도 있었고, 에러도 있었다. 그런데 원인은 없었다.

재현이 안 되는 버그는 아니었다. 오히려 잘 재현됐다. 문제는 “어디서부터 잘못됐는지”를 못 찾는 거였다. 요청은 API에서 들어오고, DB에서 데이터를 꺼내고, 중간에 여러 함수가 거친 뒤에야 예외가 났다. 마지막 스택트레이스는 친절했지만, 팀이 궁금한 건 늘 그거다.

그래서 이 값은 언제부터 이상했지?

타입 힌트를 ‘정확성’의 이야기로만 들으면 도입이 늘 늦어진다. “동적 언어인데 굳이?” “mypy 설정부터 해야 하나?” 같은 얘기만 남는다.

나는 타입 힌트를 조사 속도의 도구로 받아들이기 시작하면서부터 도입이 쉬워졌다. 코드가 덜 틀리게 만드는 도구가 아니라, 사고가 났을 때 조사를 빨리 끝내는 도구.

오늘은 그 관점에서 타입 힌트를 도입할 때 고정하면 좋은 것들을 적는다. 체크리스트로 늘어놓기보다, 한 번 터진 장애를 기준으로 어디를 고정하면 조사 시간이 줄어드는지의 이야기다.

본문에는 링크를 넣지 않고, 읽을거리는 맨 아래 참고자료로만 모았다.

타입은 ‘정답’이 아니라 조사 비용을 줄이는 장치다

Talk Python의 Typing Council 에피소드(참고자료)를 들으면, 타입은 단순히 문법 논쟁이 아니라 “파이썬 생태계가 어떻게 합의를 쌓아가는지”에 대한 이야기로 들린다. 그 합의는 성능보다도, 협업과 유지보수의 현실에서 나온다.

내가 실무에서 타입 힌트를 좋아하게 된 이유도 비슷하다. 타입이 있으면 코드가 100% 맞아지진 않는다. 대신 이런 질문이 빨라진다.

이 함수는 뭘 받아야 하지?
이 값은 None이 될 수 있나?
여기서 문자열이 들어오는 게 맞나?

중요한 건 질문이 “리뷰 타이밍”에만 나오지 않는다는 거다. 장애 조사에서 이 질문들이 늦게 나오면, 팀은 로그를 뒤지고 DB를 뒤지고 결국 사람의 기억을 뒤진다.

타입 힌트를 도입할 때 내가 먼저 보는 건 mypy가 아니라, 경계다.

외부에서 들어오는 입력(API 요청)
외부에서 나가는 출력(API 응답)
DB에서 들어오는 데이터(ORM/ODM 결과)

이 경계에서 타입이 흔들리면, 그 다음부터는 모든 게 흔들린다. 그래서 타입 힌트는 함수 내부의 ‘멋’이 아니라 경계의 ‘계약’으로 시작하는 게 낫다.

예외/로그는 타입의 일부다: logger.exception을 기본값으로 만들기

Peter Bengtsson의 글(참고자료)은 짧은데, 운영에서 체감되는 차이를 정확히 짚는다. logger.error를 쓸지 logger.exception을 쓸지.

장애 조사에서 팀이 원하는 건 “에러 메시지”가 아니라 문맥이다. 스택트레이스, 예외 체인, 그리고 “여기까지 오기 전에 무슨 값이었는지” 같은 단서.

그래서 나는 예외를 기록할 때는 기본값을 logger.exception으로 둔다. 그리고 그 습관을 타입 힌트와 함께 묶는다.

예외를 잡는다면, 어떤 예외를 잡는지 타입으로 드러나야 한다
예외를 기록한다면, 스택트레이스를 남겨야 한다
예외를 변환한다면, 어디서 변환하는지 고정돼야 한다

아래는 실전에서 흔히 쓰는 형태다.

import logging

log = logging.getLogger(__name__)


def load_user(user_id: str) -> "User":
    try:
        return fetch_user(user_id)
    except Exception:
        # 운영에서 필요한 건 메시지보다 스택트레이스와 문맥이다.
        log.exception("failed to load user", extra={"user_id": user_id})
        raise

이 코드가 타입 힌트랑 무슨 상관이냐고 묻는다면, 상관이 있다.

load_user는 User를 돌려줘야 한다
못 돌려주면 예외를 올린다

즉, 반환 타입이 흔들리지 않는다. 이게 조사 속도를 올린다. “가끔 None” 같은 반환이 섞이면, 조사자는 모든 호출부를 의심해야 한다.

DB 레이어(ORM/ODM)는 취향이 아니라 경계다: 변환 위치를 고정하기

ORM이냐 ODM이냐, 혹은 raw SQL이냐 같은 논쟁은 오래 간다. Israel Fruchter의 글(참고자료)도 결국 그 논쟁이 ‘끝난’ 게 아니라, 여전히 어떤 문제를 풀고 있는지로 읽힌다.

내가 이 논쟁을 실무에서 다루는 방식은 “좋다/나쁘다”가 아니다. 어디에서 타입이 변하는지를 고정하는 쪽이다.

조사 속도가 느려지는 전형적인 패턴은 이거다.

DB에서 나온 객체가 dict처럼 쓰인다
dict처럼 쓰이던 값이 어느 날 모델 객체로 바뀐다
호출부는 모르고, 런타임에서 깨진다

그래서 변환 위치를 한 군데로 고정한다. “DB → 도메인” 변환은 Repository에서만.

그리고 이 규칙이 지켜지지 않은 날이 있다. ORM 모델을 그대로 서비스 레이어까지 올려보낸 PR이 급하게 머지됐고, 그 다음 날부터 로그는 늘었는데 원인을 못 찾는 시간이 길어졌다. 어느 곳에서는 row["email"]로 접근했고, 다른 곳에서는 row.email로 접근했다. 둘 다 돌아가는 것처럼 보였지만, 한쪽은 None이 섞이는 순간 조용히 깨졌다. 조사자는 코드가 아니라 ‘형태’를 쫓느라 시간을 버렸다.

from dataclasses import dataclass


@dataclass(frozen=True)
class User:
    id: str
    email: str


class UserRepo:
    def get(self, user_id: str) -> User:
        row = self._fetch_row(user_id)  # ORM/SQL 결과(여기까진 어떤 형태든 상관없음)
        # 변환은 여기서만 한다.
        return User(id=str(row["id"]), email=str(row["email"]))

이렇게 해두면, ORM/ODM을 바꾸는 건 내부 구현의 문제로 격리된다. 그리고 가장 중요한 건 장애 조사에서 “의심 범위”가 줄어든다는 점이다.

User 타입이 깨졌다면, repo 안을 보면 된다
API 응답이 이상하면, 변환/직렬화 경계를 보면 된다

즉, 타입 힌트는 여기서 “이상한 값이 어디서 들어왔는지”를 찾는 지도 역할을 한다.

점진 도입: mypy/pyright는 마지막에 얹는다

타입 체커를 도입하면 좋다. 그런데 타입 체커를 켜기 전에 먼저 고치면 효과가 큰 것들이 있다.

내가 타입 체커를 켜기 전에 먼저 손보는 건, 거창한 설정이 아니라 몇 가지 습관이다.

반환값은 깔끔하게: 성공이면 성공 타입, 실패면 예외(또는 Result 타입)로 정리한다.
예외 변환은 한 군데로: 외부 API 예외든 DB 예외든, 도메인 예외로 바꾸는 자리를 고정한다.
“가끔 None”은 숨기지 않는다: 없애거나, 타입으로 드러내서 호출자가 결정하게 만든다.

여기서 내가 자주 쓰는 건 단순한 Result 타입이다. 정답이 아니라, 조사 비용을 낮추는 도구로.

from dataclasses import dataclass
from typing import Generic, TypeVar

T = TypeVar("T")


@dataclass(frozen=True)
class Ok(Generic[T]):
    value: T


@dataclass(frozen=True)
class Err:
    error: Exception

이 타입이 모든 문제를 풀진 않는다. 다만 팀이 “성공/실패”를 코드에서 같은 언어로 말하게 만든다.

그리고 그 다음에 mypy/pyright를 켠다. 이미 경계와 예외와 반환이 정리돼 있으면, 타입 체커는 잔소리가 아니라 도움으로 느껴진다.

타입 힌트는 끝내 완벽한 정답이 아니다. 대신 장애 조사에서 ‘뇌의 캐시’를 절약해준다. 어디를 보면 되는지, 무엇이 들어와야 하는지, 무엇이 들어오면 안 되는지.

여기서 한 가지 현실적인 장점이 더 있다. 타입 힌트가 깔끔한 팀은 질문이 바뀐다. “왜 깨졌지?”가 아니라 “어느 경계에서 깨졌지?”가 된다. 그 질문 변화 하나로, 조사 시간이 반으로 줄어든다.

그게 내가 타입 힌트를 운영 도구라고 부르는 이유다.

참고자료

Talk Python To Me — #539: Catching up with the Python Typing Council
- https://talkpython.fm/episodes/show/539/catching-up-with-the-python-typing-council
Peter Bengtsson — logger.error or logger.exception in Python
- http://www.peterbe.com/plog/logger.error-or-logger.exception
Israel Fruchter — Maybe ORM/ODM are not dead? Yet…
- http://fruch.github.io/python/2026/03/06/maybe-orm-odm-not-dead-yet

Django에서 트랜잭션 관리하기

Django에서 트랜잭션 관리하기 안녕하세요! 오늘은 Django에서 데이터베이스 트랜잭션을 효과적으로 관리하는 방법에 대해 알아보겠습니다. 1. 트랜잭션의 중요성 트랜잭션은 데이터베이스의 일관성과 무결성을 보장하는 중요한 개념입니다. Django에서는 여러 가지 방법으로 트랜잭션을 관리할 수 있습니다. 1.1 기본 개념 원자성(Atomicity) : 트랜잭션은 모두 실행되거나 모두 실행되지 않아야 합니다. 일관성(Consistency) : 트랜잭션 전후로 데이터베이스의 일관성이 유지되어야 합니다. 격리성(Isolation) : 동시에 실행되는 트랜잭션들이 서로 영향을 주지 않아야 합니다. 지속성(Durability) : 완료된 트랜잭션의 결과는 영구적으로 저장되어야 합니다. 2. Django의 트랜잭션 관리 2.1 기본 설정 # settings.py DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'mydatabase', 'USER': 'myuser', 'PASSWORD': 'mypassword', 'HOST': 'localhost', 'PORT': '5432', 'ATOMIC_REQUESTS': True, # 모든 뷰를 트랜잭션으로 래핑 } } 2.2 데코레이터 사용 from django.db import transaction @transaction.atomic def create_order(user, items): order = Order.objects.create(user=...

자세한 내용 보기

If Dev Then ?

이 블로그 검색