Recursos para levar boas decisões direto ao trabalho

1. Tutoriais passo a passo

Suba dependências locais com Docker Compose

1. Crie um compose.yaml na pasta da solução para a dependência usada localmente.
2. Use uma versão explícita da imagem e configure uma porta local, sem expor o serviço desnecessariamente.
3. Use credenciais descartáveis apenas para desenvolvimento; não reutilize nem versione segredos de produção.
4. Suba o serviço, espere ficar saudável e configure a aplicação para se conectar pelo nome do serviço.
5. Rode migrations e dados de demonstração de forma repetível; descarte o volume apenas quando quiser apagar estado local.

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: local-dev-only
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  db-data:

docker compose up -d db
docker compose ps
# Ao terminar, pare os serviços mantendo os dados locais:
docker compose down
# Para descartar dados de desenvolvimento e reiniciar do zero:
docker compose down --volumes

O exemplo usa senha fixa somente para um banco local descartável: não use esse padrão em ambientes compartilhados ou produção. Ajuste a versão da imagem, health check e credenciais à política do projeto.

Este é um roteiro, não um compose universal: porta, usuário, volume e health check dependem da imagem escolhida. Para o fluxo de imagem de produção, consulte Docker para .NET; para bancos em testes, veja testes de integração com ASP.NET Core.

Investigue uma consulta lenta do EF Core

1. Identifique a rota, o caso de uso e o intervalo em que a latência aumentou.
2. Use telemetria para ver número, duração e ordem das consultas relacionadas.
3. Capture a consulta parametrizada com segurança; evite expor dados sensíveis nos logs.
4. Analise o plano real e compare linhas estimadas com as observadas.
5. Altere uma coisa por vez — projeção, índice, paginação ou carregamento — e meça de novo.

Consulte o guia de performance no EF Core e SQL e a página de observabilidade.

2. Guias de referência

Referência rápida para investigar latência

Não alerte por todo valor isolado. Relacione o sinal com impacto ao usuário, orçamento de erro e ação de resposta. Aprofunde em observabilidade e resiliência.

Diagrama rápido: como uma porta protege o núcleo

3. Checklists reutilizáveis

Antes de publicar uma mudança

• Critérios de aceite e comportamento de falha foram revistos.
• Configuração e segredos não foram adicionados à imagem ou ao repositório.
• Logs, métricas e traces oferecem contexto sem registrar dados sensíveis.
• Timeouts, retries e idempotência foram definidos para integrações.
• Migrações e procedimento de reversão ou correção foram considerados.
• A equipe sabe como detectar falha e quem deve responder.

0 de 6 itens marcados.

Revisão operacional de uma fila

• Identificador de mensagem estável e consumidor idempotente.
• Retry limitado com atraso; dead-letter inspecionável e com dono.
• Concorrência, prefetch ou paralelismo ajustados à capacidade da dependência.
• Profundidade e idade das mensagens têm alerta associado a ação.
• Procedimento de replay não repete efeitos de negócio sem proteção.

Use este checklist como ponto inicial e ajuste-o ao risco, SLO e plataforma. Veja também Definition of Done e Saga, Outbox e Inbox.

4. Estudos de caso

Pedidos demorando após aumentar o tráfego

Cenário didático fictício: uma loja recebe reclamações de checkout lento depois de uma campanha. O time suspeita do banco e considera migrar imediatamente para Redis e Kafka. Antes da mudança, monta uma linha do tempo usando traces e métricas.

1. O percentil alto de latência aumenta junto com o tempo de espera por uma API de estoque externa.
2. Retries imediatos ampliam o número de chamadas durante a degradação e acumulam requisições no serviço de checkout.
3. O time reduz o prazo da chamada, limita concorrência e aplica retries com backoff somente a falhas transitórias.
4. Para o fluxo assíncrono de confirmação, monitora idade da fila e idempotência em vez de tratar cada atraso como erro definitivo.
5. Depois de estabilizar, mede consultas ao banco e encontra uma projeção excessiva em uma rota separada; otimiza essa consulta com evidência.

Aprendizado: o sintoma “checkout lento” não identifica a causa. Observabilidade ajudou a localizar espera; resiliência conteve a dependência degradada; a otimização SQL foi aplicada apenas onde a medição indicou. Este exemplo é ilustrativo, não um relato de incidente real.

Leia sobre resiliência, observabilidade e performance no EF Core.

Decidir se um módulo deve virar serviço

Cenário didático fictício: uma equipe propõe extrair faturamento para microsserviço porque o módulo tem muitas dependências internas. Ao mapear mudanças, descobre que as mesmas pessoas implantam os dois módulos, as regras ainda mudam semanalmente e a operação exige consistência imediata entre eles.

Em vez de dividir por antecipação, a equipe define uma API interna, remove referências diretas ao banco do outro módulo e cria verificações arquiteturais. Após medir o acoplamento, documenta eventos de domínio e deixa uma futura extração possível. A fronteira melhora sem adicionar chamadas de rede e consistência eventual antes de existir um benefício operacional claro.

Este caso também é ilustrativo; para os critérios, leia monólito modular ou microsserviços e testes de arquitetura em .NET.

5. Comparações para orientar escolhas

Kafka, RabbitMQ ou Azure Service Bus?

A tabela é uma heurística inicial, não uma classificação. Compare requisitos de ordering, replay, throughput, latência, operação, disponibilidade e habilidade da equipe. Leia os guias de Kafka, RabbitMQ e Azure Service Bus.

SQL Server ou PostgreSQL?

Comece por requisitos, custo total, equipe, hospedagem, recuperação e recursos realmente usados. O provider do EF Core não apaga diferenças de SQL, migrations, índices e concorrência. A resposta útil costuma vir de uma prova de conceito pequena com consultas e operação representativas, não de uma disputa abstrata. Veja a comparação completa.

6. Receitas de código

Retry exponencial com limite

O exemplo ilustra o cálculo do atraso entre tentativas; a execução também precisa respeitar cancelamento e prazo total. Em produção, acrescente jitter e classificação de erros. Não repita falhas permanentes ou operações não idempotentes sem proteção.

static TimeSpan AtrasoRetry(int tentativa, TimeSpan baseDelay, TimeSpan limite)
{
    var expoente = Math.Clamp(tentativa - 1, 0, 20);
    var fator = Math.Pow(2, expoente);
    var milissegundos = Math.Min(baseDelay.TotalMilliseconds * fator,
                                 limite.TotalMilliseconds);
    return TimeSpan.FromMilliseconds(milissegundos);
}

Endpoint restrito por política no ASP.NET Core

builder.Services.AddAuthorization(options =>
    options.AddPolicy("Relatorios:Leitura", policy =>
        policy.RequireAuthenticatedUser()
              .RequireClaim("scope", "relatorios.read")));

app.MapGet("/relatorios", ObterRelatorios)
   .RequireAuthorization("Relatorios:Leitura");

Confirme o formato de claims do seu provedor; nomes e tipos podem variar. Veja o guia de autenticação em ASP.NET Core.

7. Glossário de engenharia

Backoff

Aumento do intervalo entre novas tentativas para reduzir pressão durante falhas.

Bulkhead

Limite de recursos ou concorrência que impede uma dependência de consumir toda a capacidade.

Cache-aside

Estratégia em que a aplicação consulta cache, busca a fonte de verdade em caso de miss e preenche o cache.

Consumer group

Conjunto de consumidores que divide o trabalho de partições de um tópico Kafka.

Dead-letter queue (DLQ)

Destino de mensagens que não foram processadas conforme a política normal e precisam de diagnóstico.

Idempotência

Propriedade de repetir uma operação sem alterar o resultado efetivo após a primeira execução.

OpenTelemetry

Conjunto aberto de APIs, SDKs e convenções para instrumentar telemetria.

Outbox

Registro transacional de evento junto com a alteração local, publicado posteriormente por um dispatcher.

RAG

Geração aumentada por recuperação: busca contexto relevante e o fornece ao modelo antes da resposta.

SLO

Objetivo mensurável de nível de serviço, como disponibilidade ou latência dentro de uma janela definida.

Trace

Representação correlacionada das etapas percorridas por uma operação.

TTL

Tempo de vida configurado após o qual um dado armazenado pode expirar.

8. Mapa de decisão: qual conteúdo ler primeiro?

O mapa sugere um ponto de partida, não uma causa automática. O caminho estático permanece disponível na tabela:

9. Ferramentas interativas

Estimador didático de espera em retries

Estimativa para backoff exponencial com full jitter: cada atraso sorteado fica entre zero e o limite da tentativa. O cálculo mostra média teórica e pior caso dos atrasos; não inclui tempo de rede, processamento nem timeout. Não é uma recomendação de política pronta para produção.

Preencha os valores para estimar a espera.

Retry não substitui timeout, cancelamento e idempotência. Veja resiliência em sistemas distribuídos.

10. Perguntas frequentes

11. Notas de atualização e fontes oficiais

• 5 de novembro de 2026: publicação inicial deste centro de recursos com tutoriais, checklists, comparação de mensageria, ferramentas e glossário.

Tecnologias mudam. Antes de aplicar detalhes de produto, confira a documentação oficial vigente e a versão utilizada pelo projeto:

• Microsoft Learn: autenticação no ASP.NET Core
• Microsoft Learn: performance do EF Core
• Docker Docs: builds multi-stage
• OpenTelemetry: documentação
• Apache Kafka: documentação
• RabbitMQ: documentação
• Microsoft Learn: Azure Service Bus
• Redis: documentação
• PostgreSQL: documentação e Microsoft Learn: SQL Server

Revise este histórico apenas quando houver uma atualização real de conteúdo; não altere datas para sugerir frescor que não existiu.