Jak zarządzać ustawieniami za pomocą Pydantic?

Question

Accepted Answer

Aplikacje FastAPI zarządzają konfiguracją za pomocą **`pydantic-settings`** (`BaseSettings`) — klasy, która odczytuje konfigurację ze **zmiennych środowiskowych** (i plików `.env`) z **walidacją i konwersją typów**, ukrywając sekrety poza kodem i zapewniając poprawność konfiguracji przy uruchomieniu.

## Definiowanie ustawień

```python
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "My API"
    database_url: str                       # required — must be provided
    secret_key: str                          # required (a secret)
    debug: bool = False
    max_connections: int = 10

class Config:
        env_file = ".env"                    # also read from a .env file

settings = Settings()                        # reads & VALIDATES env vars at startup
```

`BaseSettings` automatycznie odczytuje każde pole ze zmiennej **środowiskowej** o pasującej nazwie (np. `DATABASE_URL`), konwertuje typy (`"true"` → `bool`, `"10"` → `int`) i **waliduje** — brak wymaganej wartości lub błędny typ powoduje natychmiastową porażkę przy uruchomieniu z wyraźnym komunikatem błędu (fail-fast).

## Używanie ustawień (poprzez wstrzykiwanie zależności)

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

@lru_cache                              # create the Settings once (cached)
def get_settings():
    return Settings()

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

Wstrzykiwanie ustawień poprzez buforowaną zależność sprawia, że są one **testowalny** (override w testach) i zapewnia pojedynczą instancję.

## Plik .env i sekrety

```bash
# .env — local config, GITIGNORED (never commit secrets)
DATABASE_URL=postgresql://localhost/mydb
SECRET_KEY=dev-secret
DEBUG=true
```

```text
✓ Keep secrets in env vars / .env (gitignored); commit a .env.example documenting keys
✓ In production, inject config via the platform's environment / secret manager
✓ Validation at startup catches misconfiguration immediately (not deep in a request)
```

## Dlaczego to ważne

Poprawne zarządzanie ustawieniami jest zarówno **koniecznością operacyjną** (aplikacje potrzebują innej konfiguracji na dev/staging/produkcję) jak i **wymogiem bezpieczeństwa** (sekrety takie jak adresy URL baz danych i klucze nigdy nie mogą być zakodowne w kontroli wersji — powszechne, poważne naruszenie).

`BaseSettings` Pydantic zapewnia idiomatyczne rozwiązanie FastAPI, a zrozumienie go jest ważną wiedzą codzienną.

Jego kluczowe zalety: odczytywanie konfiguracji ze **zmiennych środowiskowych** (ukrywanie sekretów poza kodem, podejście twelve-factor) z automatyczną **konwersją typów i walidacją** — dzięki temu błędna konfiguracja szybko zawodzi przy uruchomieniu z wyraźnym komunikatem błędu, zamiast być zagmatwnym błędem czasu wykonywania.

W połączeniu z wstrzykiwaniem zależności (uczyniając ustawienia testowalnymi i singletonowymi) i praktyką ignorowania plików `.env` w kontroli wersji do lokalnego rozwoju, otrzymujesz bezpieczną, walidowaną, odpowiednią dla środowiska konfigurację.

Wiedzenie, jak definiować ustawienia, używać ich poprzez DI i bezpiecznie obsługiwać sekrety, jest fundamentalne dla budowania gotowych do produkcji aplikacji FastAPI.