🚀 Guia Rápido de Referência - Módulos Comuns C-Suite
Última atualização: 2025-12-01
📋 Índice Rápido
- Logging
- Error Handling
- Health Checks
- Métricas
- Tracing
- Circuit Breaker
- Event Sourcing
- Business Metrics
- HTTP Client
- Configuração
Logging
from common.common_logging import setup_logging, get_logger
# No startup do app
setup_logging(
app_name="meu-app",
log_level=os.getenv("LOG_LEVEL", "INFO"),
log_format="json" if os.getenv("ENV") == "production" else "text",
structured=True
)
# Em qualquer módulo
logger = get_logger(__name__)
logger.info("Mensagem de log", extra={"key": "value"})
Error Handling
from common.common_errors import CSuiteError, ErrorCode, error_handler
# Registrar handler global
app.add_exception_handler(Exception, error_handler)
# Lançar erro padronizado
raise CSuiteError(
error_code=ErrorCode.RESOURCE_NOT_FOUND,
message="Recurso não encontrado",
details={"resource_id": 123}
)
Health Checks
from common.common_health import create_health_router
health_router = create_health_router(
app_name="meu-app",
dependencies=[
"database:csuite",
"external_service:api_externa:http://api.externa.com"
]
)
app.include_router(health_router)
Métricas
from common.common_metrics import create_metrics_router, create_metrics_middleware
metrics_router = create_metrics_router("meu-app")
app.include_router(metrics_router)
app.middleware("http")(create_metrics_middleware("meu-app"))
Tracing
from common.common_tracing import setup_tracing, get_tracer
# No startup
setup_tracing(
app=app,
service_name="meu-app",
jaeger_host=os.getenv("JAEGER_HOST", "localhost"),
jaeger_port=int(os.getenv("JAEGER_PORT", "14250"))
)
# Em funções
tracer = get_tracer("meu-modulo")
with tracer.start_as_current_span("operacao") as span:
span.set_attribute("parametro", valor)
# ... código ...
Circuit Breaker
from common.common_http_client import get_http_client
async with get_http_client(
base_url="http://api.externa.com",
timeout=5.0,
circuit_breaker_name="api_externa",
failure_threshold=3,
timeout_seconds=30.0
) as client:
response = await client.get("/endpoint")
data = response.json()
Event Sourcing
from common.common_event_sourcing import get_event_store, EventType
event_store = get_event_store("csuite")
event_id = event_store.record_event(
event_type=EventType.DECISION_CREATED,
aggregate_id=str(decision_id),
aggregate_type="decision",
payload={"decision": decision_data},
metadata={"user_id": user_id}
)
Business Metrics
from common.common_business_metrics import define_business_counter, get_business_metric
# No startup
define_business_counter(
"decisions_total",
"Total number of decisions made",
["org_id", "decision_type"]
)
# No código
get_business_metric("decisions_total").labels(
org_id="1",
decision_type="offer"
).inc()
HTTP Client
from common.common_http_client import get_http_client
# Com circuit breaker automático
async with get_http_client(
base_url="http://api.externa.com",
timeout=5.0,
circuit_breaker_name="api_externa"
) as client:
response = await client.post("/endpoint", json={"data": "value"})
Configuração
from common.core_config import get_csuite_api_url, get_fourc_decision_api_url
# URLs de serviços
csuite_url = get_csuite_api_url()
decision_url = get_fourc_decision_api_url()
# Configuração de banco
from common.core_config import get_db_config
db_config = get_db_config("csuite")
🔧 Padrão de Migração Completo
import os
import sys
from pathlib import Path
from fastapi import FastAPI
# Adiciona common ao path
COMMON_PATH = str(Path(__file__).resolve().parents[N]) # Ajuste N
sys.path.insert(0, COMMON_PATH)
# Imports com fallback
try:
from common.common_logging import setup_logging, get_logger
LOGGING_ENABLED = True
except ImportError:
LOGGING_ENABLED = False
try:
from common.common_errors import error_handler
ERROR_HANDLING_ENABLED = True
except ImportError:
ERROR_HANDLING_ENABLED = False
# ... outros imports ...
app = FastAPI(title="Meu App")
# Configura logging
if LOGGING_ENABLED:
setup_logging(app_name="meu-app", ...)
logger = get_logger(__name__)
else:
import logging
logger = logging.getLogger(__name__)
# Configura error handling
if ERROR_HANDLING_ENABLED:
app.add_exception_handler(Exception, error_handler)
# ... resto da configuração ...
📚 Documentação Completa
Para documentação detalhada de cada módulo, consulte:
docs/MIGRACAO_MODULOS_COMUNS.md- Guia completo de migraçãodocs/DISTRIBUTED_TRACING.md- Distributed tracingdocs/CIRCUIT_BREAKER.md- Circuit breakerdocs/EVENT_SOURCING.md- Event sourcing- E mais em
docs/
Última atualização: 2025-12-01