FastAPI 프로젝트에 Pydantic BaseSettings로 환경 변수 관리 개선하기

문제 상황

사내 FastAPI 프로젝트에서 환경 변수를 python-dotenv로 관리하고 있었다. 코드 곳곳에서 os.getenv()로 값을 가져오다 보니 타입 체크가 불가능하고, 필수 값 누락을 런타임에 발견하는 일이 잦았다.

# 기존 방식
DATABASE_URL = os.getenv("DATABASE_URL")
MAX_CONNECTIONS = int(os.getenv("MAX_CONNECTIONS", "10"))

Pydantic BaseSettings 도입

Pydantic v1.8부터 제공하는 BaseSettings를 활용해 환경 변수를 클래스로 관리하도록 변경했다.

from pydantic import BaseSettings, PostgresDsn

class Settings(BaseSettings):
    database_url: PostgresDsn
    max_connections: int = 10
    redis_host: str
    debug: bool = False
    
    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

개선 효과

타입 안정성 확보
환경 변수가 자동으로 선언된 타입으로 변환된다. int, bool 등의 변환을 직접 할 필요가 없다.

필수 값 검증
기본값이 없는 필드는 자동으로 필수가 된다. 앱 시작 시 누락된 환경 변수가 있으면 명확한 에러 메시지와 함께 실행이 중단된다.

IDE 자동완성
settings.database_url처럼 접근하면 IDE에서 자동완성이 되고, 오타를 사전에 잡을 수 있다.

주의점

.env 파일은 개발 환경에서만 사용하고, 프로덕션에서는 실제 환경 변수로 주입해야 한다. Docker나 k8s ConfigMap을 통해 관리하는 것을 권장한다.

환경 변수가 많아지면 Settings 클래스를 용도별로 분리하는 것도 고려할 만하다.