Aplicações FastAPI gerenciam configuração com pydantic-settings (BaseSettings) — uma classe que lê a configuração de variáveis de ambiente (e arquivos .env) com , mantendo segredos fora do código e garantindo que a configuração esteja correta na inicialização.
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 lê automaticamente cada campo de uma variável de ambiente correspondente (por exemplo, DATABASE_URL), converte tipos ("true" → bool, "10" → int) e valida — um valor obrigatório ausente ou tipo incorreto falha imediatamente na inicialização com um erro claro (falha rápida).
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}
Injetar configurações por meio de uma dependência em cache as torna testáveis (sobrescrever nos testes) e garante uma única instância.
# .env — local config, GITIGNORED (never commit secrets)
DATABASE_URL=postgresql://localhost/mydb
SECRET_KEY=dev-secret
DEBUG=true
✓ 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)
O gerenciamento adequado de configurações é tanto uma necessidade operacional (aplicações precisam de configurações diferentes em dev/staging/produção) quanto um requisito de segurança (segredos como URLs de banco de dados e chaves nunca devem ser codificados no controle de código-fonte — uma falha comum e séria).
O BaseSettings do Pydantic fornece a solução idiomática do FastAPI, e entendê-lo é conhecimento importante do dia a dia.
Suas principais vantagens: leitura de configuração de variáveis de ambiente (mantendo segredos fora do código, a abordagem twelve-factor) com conversão de tipo e validação automáticas — então a configuração incorreta falha rapidamente na inicialização com um erro claro em vez de uma falha em tempo de execução confusa.
Combinado com injeção de dependência (tornando as configurações testáveis e singleton) e a prática de arquivos .env ignorados pelo git para desenvolvimento local, isso oferece a você configuração segura, validada e apropriada ao ambiente.
Saber como definir configurações, usá-las via DI e gerenciar segredos com segurança é fundamental para construir aplicações FastAPI prontas para produção.