Pydantic으로 설정을 어떻게 관리합니까?

Question

Accepted Answer

FastAPI 애플리케이션은 **`pydantic-settings`**(`BaseSettings`)로 설정을 관리합니다. **환경 변수**(및 `.env` 파일)로부터 **validation과 타입 변환**과 함께 설정을 읽는 클래스로, 비밀(secret)을 코드 밖에 두고 시작 시점에 설정이 올바른지 보장합니다.

## 설정 정의하기

```python
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "My API"
    database_url: str                       # 필수 — 반드시 제공되어야 함
    secret_key: str                          # 필수 (비밀)
    debug: bool = False
    max_connections: int = 10

class Config:
        env_file = ".env"                    # .env 파일에서도 읽음

settings = Settings()                        # 시작 시 환경 변수를 읽고 검증함
```

`BaseSettings`는 각 필드를 일치하는 **환경 변수**(예: `DATABASE_URL`)로부터 자동으로 읽고, 타입을 변환하며(`"true"` → `bool`, `"10"` → `int`), **검증**합니다. 누락된 필수 값이나 잘못된 타입은 시작 시점에 명확한 오류와 함께 즉시 실패합니다(fail-fast).

## 설정 사용하기 (dependency injection을 통해)

```python
from functools import lru_cache
from fastapi import Depends

@lru_cache                              # Settings를 한 번만 생성 (캐시됨)
def get_settings():
    return Settings()

@app.get("/info")
def info(settings: Settings = Depends(get_settings)):
    return {"app": settings.app_name, "debug": settings.debug}
```

캐시된 의존성을 통해 설정을 주입하면 **테스트 가능**해지고(테스트에서 재정의) 단일 인스턴스가 보장됩니다.

## .env 파일과 비밀

```bash
# .env — 로컬 설정, GITIGNORE됨 (비밀을 절대 커밋하지 마세요)
DATABASE_URL=postgresql://localhost/mydb
SECRET_KEY=dev-secret
DEBUG=true
```

```text
✓ 비밀은 환경 변수 / .env(gitignore됨)에 보관; 키를 문서화하는 .env.example을 커밋
✓ 프로덕션에서는 플랫폼의 환경 / 시크릿 매니저를 통해 설정 주입
✓ 시작 시점의 validation이 잘못된 설정을 (요청 깊숙한 곳이 아닌) 즉시 포착
```

## 왜 중요한가

적절한 설정 관리는 **운영상의 필요**(앱은 dev/staging/production에 걸쳐 다른 설정이 필요)이자 **보안 요구사항**(데이터베이스 URL과 키 같은 비밀은 절대 소스 관리에 하드코딩되어서는 안 됨 — 흔하고 심각한 유출 사고)입니다.

Pydantic의 `BaseSettings`는 관용적인 FastAPI 해법을 제공하며, 이를 이해하는 것은 중요한 일상 지식입니다.

핵심 이점: **환경 변수**로부터 설정을 읽어(비밀을 코드 밖에 둠, twelve-factor 접근) 자동 **타입 변환과 validation**과 함께 처리합니다. 따라서 잘못된 설정이 혼란스러운 런타임 실패가 아니라 시작 시점에 명확한 오류로 빠르게 실패합니다.

dependency injection(설정을 테스트 가능하고 싱글톤으로 만듦)과 로컬 개발을 위한 gitignore된 `.env` 파일 관행과 결합하면, 안전하고 검증되며 환경에 적합한 설정을 얻습니다.

설정을 정의하고, DI를 통해 사용하며, 비밀을 안전하게 처리하는 방법을 아는 것은 프로덕션 준비된 FastAPI 애플리케이션을 구축하는 데 근본적입니다.