⁣Конфиг, который не ломается: строгая типизация, секреты и валидация runtime-параметров

В production конфиг часто выглядит как мешанина os.environ с копипастой и опечатками в именах переменных. Это прямой путь к ошибке при старте или утечке секрета в лог через config.dict(). Pydantic Settings v2 решает это одним классом — с типизацией, дефолтами и валидацией на этапе инициализации.

Контроль типов и дефолтов

Вы описываете структуру конфига, и если переменная не задана без дефолта — приложение не запустится. Это исключает runtime-сюрпризы. SecretStr прячет секреты в repr: даже при выводе объекта в лог api_key отображается только звездочками.

class AppConfig(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
    database_url: str
    api_key: SecretStr
    max_connections: int = 10
    debug: bool = False

    @field_validator("max_connections")
    @classmethod
    def ensure_positive(cls, v):
        if v <= 0:
            raise ValueError("must be positive")
        return v

    @field_validator("database_url")
    @classmethod
    def validate_scheme(cls, v):
        if not v.startswith("postgresql://"):
            raise ValueError("Only PostgreSQL supported")
        return v

Бизнес-логика на уровне конфига

Валидаторы проверяют не только типы, но и бизнес-правила. Для data pipeline, требующего только определенный диалект SQL, это задается в одном месте, а не размазывается по модулям. Такой подход делает код читаемее и проще в поддержке.

Типичная ошибка: лишние переменные из .env

Без extra="ignore" случайная строка в .env вызовет ошибку. Другая проблема — путаница с env_prefix в подмодулях, когда конфиги перекрывают поля друг друга. Включите env_nested_delimiter для плоских переменных с вложенными моделями, чтобы избежать лишней вложенности.

Production-ready: кэшируем и расширяем

Для однократного создания конфига используем lru_cache, а дальше можно миксовать с аргументами командной строки через CliSettingsSource. С одним источником истины для env, файлов и флагов приложение становится проще тестировать и развёртывать.

Вывод: Инкапсуляция конфига через Pydantic Settings — это не просто типы, а гарантия, что приложение не стартанёт с неправильными данными, а секреты не утекут из-за банального логирования.