Guia Rapido Referencia

🚀 Guia Rápido de Referência - Módulos Comuns C-Suite

Última atualização: 2025-12-01


📋 Índice Rápido

  1. Logging
  2. Error Handling
  3. Health Checks
  4. Métricas
  5. Tracing
  6. Circuit Breaker
  7. Event Sourcing
  8. Business Metrics
  9. HTTP Client
  10. 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:


Última atualização: 2025-12-01

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir