DEV Community

Thaylon Lopes
Thaylon Lopes

Posted on

TL.LiteCore vs TL.ResilientCore: Minimal API leve ou Clean Architecture com Outbox? O guia prático para ajudar decidir no .NET

Na arquitetura de software, não existem soluções perfeitas. Nem toda API precisa de RabbitMQ e Clean Architecture: como decido a estrutura dos meus projetos .NET avaliando trade-offs, contêineres e custos de nuvem.

No primeiro artigo desta série, compartilhei a jornada de abandonar a velha pasta Utils para construir um ecossistema de micro-bibliotecas no NuGet e a necessidade de criar templates no .NET CLI (dotnet new) para acelerar o "Day 0" das aplicações.

Lá, mencionei um princípio que levo a sério na engenharia de software: não existem soluções perfeitas, apenas trade-offs. Tentar forçar uma única arquitetura para resolver todos os cenários da organização inevitavelmente gera problemas.

Uma das decisões mais estratégicas ao iniciar um novo serviço é: qual a arquitetura escolher para este problema de negócio?

Se você escolhe uma arquitetura pesada (Clean Architecture estrita, CQRS, RabbitMQ, Transactional Outbox e containers de infraestrutura) para uma API simples de consulta ou um webhook satélite, você impõe um custo desnecessário de complexidade ao time e infla o consumo de nuvem (FinOps).

Por outro lado, se escolhe uma estrutura rasa e minimalista para um fluxo transacional crítico (como checkout ou faturamento), logo sentirá a falta de garantias de entrega de mensagens, resiliência de rede com circuit breakers e rastreabilidade distribuída quando algo quebrar em produção.

Para orientar essa escolha com clareza, estruturei o ecossistema inicialmente em torno de dois templates: TL.LiteCore e TL.ResilientCore.

Este artigo é um guia prático de como avaliar esses trade-offs, confrontar evidências de código e tomar a decisão correta no seu próximo projeto.


🧭 A Matriz de Decisão Arquitetural

A tabela a seguir resume as dimensões técnicas, garantias transacionais e perfil operacional de cada template:

Dimensão de Análise ⚡ TL.LiteCore (O Ágil & Leve) 🛡️ TL.ResilientCore (O Robusto & Resiliente)
Estilo Arquitetural Minimal APIs REST síncronas Clean Architecture Estrita & CQRS
Comunicação Primária Síncrona via HTTP REST / OpenAPI Assíncrona via Mensageria (RabbitMQ) e HTTP
Modelo de Consistência Consistência Imediata (ACID local em banco) Consistência Eventual e Transações Distribuídas
Garantia de Mensageria Nenhuma (bloqueada por Architecture Tests) Transactional Outbox & Inbox Patterns
Resiliência de Rede Timeouts e retries pontuais Pipelines compostos Polly v8 (Retry + Jitter + Circuit Breaker)
Tempo de Startup (Boot) < 80 milissegundos 350 ms a 600 ms
Consumo de Memória (RAM) ~35 MB a 50 MB (Kestrel Minimal API pós-warmup) ~75 MB a 140 MB (API com Pools, AMQP e Worker ativo)
Tamanho da Imagem Docker < 110 MB (.NET 9 Chiseled) ~210 MB (.NET 9 Chiseled)
Observabilidade & Tracing Logs estruturados e ProblemDetails padronizado W3C Distributed Tracing (traceparent) + Probes corporativos
Banco em Desenvolvimento SQLite em memória ou relacional leve PostgreSQL 16 via Testcontainers / Docker
Estratégia de Testes Smoke tests em memória via WebApplicationFactory Testes de integração em containers reais
Complexidade Cognitiva Muito Baixa (curva de onboarding quase nula) Moderada a Alta (exige maturidade em DDD e eventos)

📝 Nota Metodológica de Aferição: Os dados de boot e memória foram aferidos em contêineres Linux utilizando a imagem oficial .NET 9 Chiseled (mcr.microsoft.com/dotnet/aspnet:9.0-noble-chiseled), em repouso após 50 requisições de aquecimento (warmup) das rotas de liveness (/livez). Em contêineres com Server GC habilitado em múltiplos núcleos, o runtime .NET reserva segmentos de heap dedicados por CPU lógica.


💻 Sob o Capô: A Evidência do Trade-off em Código

A melhor maneira de entender por que um modelo é leve e o outro é blindado é olhando para o código gerado em cada um:

1. No TL.LiteCore: Minimal APIs e Zero Burocracia

No TL.LiteCore, o foco é eliminar camadas indiretas desnecessárias. O endpoint se comunica diretamente com a aplicação e mapeia o resultado funcional para ProblemDetails:

// Program.cs no TL.LiteCore: Minimal API direta e tipada
app.MapGet("/v1/enderecos/{cep}", async (
    string cep, 
    ISender mediator, 
    CancellationToken ct) =>
{
    var resultado = await mediator.Send(new ConsultarEnderecoQuery(cep), ct);

    // Converte automaticamente Result.Success para HTTP 200 Ok
    // ou Result.Failure para ProblemDetails com status HTTP correto (404, 400, etc.)
    return resultado.ToHttpResult();
})
.WithName("ConsultarEndereco")
.WithTags("Enderecos");
Enter fullscreen mode Exit fullscreen mode

Por que este trade-off é melhor aqui?

Não há transações distribuídas, não há conexões com brokers de fila e não há background workers consumindo CPU. A requisição bate no Kestrel, consulta os dados e responde em sub-5ms. A aplicação inteira consome ~35MB a 50MB de RAM e sobe em menos de 80ms.


2. No TL.ResilientCore: Atomicidade com Transactional Outbox

No TL.ResilientCore, a regra é: nenhuma mensagem pode ser publicada no broker sem antes estar seguramente commitada no banco de dados.

Em vez de publicar diretamente no RabbitMQ dentro do handler (o que causaria inconsistência se o banco falhasse logo em seguida), o evento nasce no agregado de domínio e é capturado de forma transparente:

// CommandHandler no TL.ResilientCore: O evento de domínio é atômico à transação
public async Task<Result<Guid>> Handle(FinalizarPedidoCommand command, CancellationToken ct)
{
    var pedido = Pedido.Criar(command.ClienteId, command.Itens);

    // 1. O agregado registra o evento internamente
    pedido.AdicionarEventoDominio(new PedidoCriadoEvent(pedido.Id, pedido.Total));

    _pedidoRepository.Adicionar(pedido);

    // 2. O SaveChangesAsync aciona o InsertOutboxMessagesInterceptor:
    // O pedido E a mensagem de Outbox são salvos na MESMA transação do PostgreSQL!
    await _unitOfWork.SaveChangesAsync(ct); 

    return pedido.Id;
}
Enter fullscreen mode Exit fullscreen mode

E nos bastidores, um worker dedicado com resiliência e circuit breaker garante o despacho seguro:

// ProcessOutboxMessagesJob: BackgroundService que despacha mensagens pendentes
public class ProcessOutboxMessagesJob : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Lê o lote da tabela 'outbox_messages', publica no RabbitMQ com Publisher Confirms,
            // e marca como processada atomicamente.
            await ProcessBatchAsync(stoppingToken);
            await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Por que este trade-off é melhor aqui?

Esse modelo exige um investimento operacional maior de recursos (~75MB de RAM e 2.6% de CPU na API, além de RabbitMQ e PostgreSQL somando ~290MB) porque mantém o pool de conexões do PostgreSQL, a conexão persistente AMQP com o RabbitMQ e a thread de background do ProcessOutboxMessagesJob ativas. Em troca desse consumo, ele elimina o erro de "dinheiro cobrado sem pedido registrado". Se a rede oscilar no meio do caminho, o evento permanece seguro na tabela de Outbox para despacho garantido.


💼 4 Cenários Reais do Dia a Dia: Qual Template Escolher?

Para trazer essa decisão para a realidade do dia a dia, separei quatro cenários práticos comuns em organizações de tecnologia:

Cenário 1: Gateway de Pagamentos e Checkout de E-commerce

  • O Desafio: Quando o cliente clica em "Finalizar Pedido", a aplicação precisa debitar o cartão, reservar o estoque, emitir a nota e notificar o sistema de logística. Se a rede oscilar no meio da operação, nenhum dinheiro pode ser cobrado sem que o evento chegue aos serviços downstream.
  • A Escolha: TL.ResilientCore (dotnet new tl-resilientcore)
  • Por quê? Esse cenário exige o Transactional Outbox Pattern: o evento de pagamento é gravado atomicamente na mesma transação de banco de dados do pedido. No lado dos consumidores, o Transactional Inbox garante que eventos reprocessados devido a retries de rede sejam tratados de forma idempotente sem duplicar cobranças.

Cenário 2: Serviço de Autocompletar Endereço / Consulta de CEP

  • O Desafio: Um serviço interno recebe o CEP digitado no frontend, consulta uma base de dados relacional e devolve o logradouro para preencher o formulário. O tráfego tem picos volumosos durante campanhas de marketing.
  • A Escolha: TL.LiteCore (dotnet new tl-litecore)
  • Por quê? Trata-se de uma operação estritamente de leitura, sem efeitos colaterais de escrita e sem dependência de mensageria assíncrona. Com Minimal APIs e Dapper/EF leve, o serviço consome ~35MB a 50MB de RAM, inicializa em menos de 80ms e escala horizontalmente com facilidade em containers ou modelos de escala a zero (Serverless / Container Apps).

Cenário 3: Backend-for-Frontend (BFF) Mobile

  • O Desafio: Uma API intermediária que apenas agrega dados de dois ou três microsserviços internos diferentes, formata o JSON para a tela do aplicativo iOS/Android e devolve a resposta rápida para o smartphone.
  • A Escolha: TL.LiteCore (dotnet new tl-litecore)
  • Por quê? O BFF não deve manter regras de domínio ricas nem publicar eventos de negócio em filas. Ele precisa ser rápido, leve e ter boot veloz para manter a latência percebida pelo usuário no mínimo. Colocar RabbitMQ e CQRS aqui seria um clássico caso de sobre-engenharia acidental.

Cenário 4: Motor de Faturamento e Cobrança Recorrente

  • O Desafio: Um worker em lote que processa milhares de faturas e assinaturas ativas na virada do mês, aplicando regras de juros, multas, emissão fiscal e enviando comandos de débito.
  • A Escolha: TL.ResilientCore (dotnet new tl-resilientcore)
  • Por quê? A orquestração assíncrona, a necessidade de Dead Letter Queues (DLQ) para isolar falhas de faturamento e a auditoria transacional estrita exigem a solidez do TL.ResilientCore. Se um serviço falhar no meio do processamento, a DLQ retém o payload com contexto forense para reprocessamento posterior sem perda de dados.

🔬 O Laboratório Prático: Evidência de Baseline em Contêineres e FinOps

Para tirar essa discussão do plano teórico e confrontar esses trade-offs em um ambiente de produção moderno, montei uma bancada de testes utilizando contêineres Docker com limites de recursos (resource limits) configurados para cada perfil.

O objetivo deste teste foi aferir o baseline operacional e o custo de existência (Day 0) de cada aplicação em contêineres Linux oficiais (.NET 9 Chiseled): quanto de CPU e memória cada modelo exige da infraestrutura em repouso após o ciclo de inicialização e aquecimento (warmup).

# docker-compose.benchmark.yml (Configuração dos limites de recursos)
services:
  # Modelo Leve: 64MB de limite rígido (Cenários 2 e 3)
  tl-litecore-api:
    image: tl-litecore-api:latest
    deploy:
      resources:
        limits:
          cpus: '0.25'
          memory: 64M
        reservations:
          memory: 32M

  # Modelo Resiliente: 256MB de limite (Cenários 1 e 4)
  tl-resilientcore-api:
    image: tl-resilientcore-api:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 256M
        reservations:
          memory: 128M
    depends_on: [ tl-postgres, tl-redis, tl-rabbitmq ]
Enter fullscreen mode Exit fullscreen mode

Após subir o ambiente e disparar uma bateria de 50 requisições de aquecimento (warmup) nas rotas de liveness (/livez) para estabilizar pipelines e pools, capturei o consumo real através do comando docker stats --no-stream:

Evidência empírica de consumo de memória e CPU via docker stats

CONTAINER ID   NAME                    CPU %     MEM USAGE / LIMIT     MEM %     NET I/O           BLOCK I/O        PIDS
8c8fb38ebab9   lab-resilientcore-api   2.60%     77.05MiB / 256MiB     30.10%    35.2kB / 45kB     66.4MB / 4.1kB   17
19fa1657ea22   lab-postgres            0.03%     47.07MiB / 15.47GiB   0.30%     17.7kB / 18.9kB   64.6MB / 53.3MB  7
4a47ceb9fc56   lab-rabbitmq            0.30%     168.9MiB / 15.47GiB   1.07%     2.07kB / 126B     61.1MB / 631kB   88
1a17796c0821   lab-litecore-api        0.01%     50.72MiB / 64MiB      79.25%    16.7kB / 27.6kB   82.1MB / 12.3kB  13
49ed7a512bb6   lab-redis               0.82%     6.656MiB / 15.47GiB   0.04%     2.33kB / 126B     24.3MB / 0B      6
Enter fullscreen mode Exit fullscreen mode

O Que Essa Evidência Revela para a sua Arquitetura?

  1. A Eficiência do TL.LiteCore (~50 MB e 0.01% CPU):

    Com Minimal APIs e sem processos concorrentes em background, a aplicação consome apenas 50.72 MiB e praticamente zero de CPU (0.01%) com apenas 13 threads/PIDs. Ela cabe com folga dentro de um teto de 64MB de memória, sendo perfeita para APIs satélites, consultas de alta vazão e arquiteturas com escala a zero.

  2. O Investimento Operacional do TL.ResilientCore (Stack ~290 MB e 2.60% CPU):

    A API consome 77.05 MiB de RAM, e o ecossistema com RabbitMQ (168.9 MiB) e PostgreSQL (47.07 MiB) totaliza cerca de 293 MiB de infraestrutura. A CPU em 2.60% reflete a atividade contínua da thread do ProcessOutboxMessagesJob e das conexões AMQP. Esse investimento se justifica nos fluxos críticos em que perder uma mensagem significa inconsistência financeira grave.

  3. O Impacto em FinOps e Densidade no Kubernetes:

    Imagine um nó de cluster (ou instância de nuvem) com 4 GB de memória utilizável:

    • Alocando TL.LiteCore (com limite de 64 MB), você consegue agendar mais de 45 a 50 réplicas com margem de segurança.
    • Alocando TL.ResilientCore (com limite de 256 MB), você consegue agendar entre 12 e 14 réplicas.

Essa comparação evidencia que a escolha arquitetural não é apenas uma questão de preferência de código; é uma decisão que impacta diretamente a fatura de nuvem e a capacidade de escala da organização.


🔄 A Rota de Evolução: E se o projeto LiteCore crescer?

Uma das maiores preocupações de qualquer arquiteto ao adotar um template leve é o medo do lock-in ou de cair em um beco sem saída:

"E se eu começar uma API com o TL.LiteCore para ser rápido, mas daqui a 6 meses o negócio exigir mensageria assíncrona e resiliência avançada? Vou ter que reescrever tudo?"

A resposta é não. E essa é a beleza de uma engenharia baseada em padrões consistentes.

Como ambos os templates compartilham a mesma fundação conceitual (TL.BaseContracts, Domain, Application e o Result Pattern funcional), a migração não exige reescrever regras de negócio:

  1. O Domínio permanece intacto: As entidades, agregados e eventos de domínio continuam operando da mesma forma.
  2. A Aplicação não muda: Commands e Queries continuam retornando Result<T>.
  3. Apenas a Infraestrutura se expande: Você referencia o pacote TL.RabbitMQ, registra o InsertOutboxMessagesInterceptor no seu DbContext e ativa o ProcessOutboxMessagesJob.

O TL.LiteCore é um ponto de partida rápido que não cria barreiras caso o seu serviço precise evoluir para o TL.ResilientCore no futuro.


🏗️ A Consistência Cognitiva: O Elo Entre os Dois Mundos

A maior armadilha de manter múltiplos templates em uma empresa é a fragmentação de conhecimento: o desenvolvedor aprende a trabalhar na API "A" e, quando migra para a API "B", encontra um universo totalmente diferente.

Estruturei essa solução apoiando ambos os templates nas mesmas micro-bibliotecas fundamentais:

┌──────────────────────────────────────────────────────────────────┐
│                   🏰 OS TEMPLATES DE PROJETO                     │
│    TL.LiteCore (Síncrono)     │   TL.ResilientCore (Eventos)     │
└───────────────────────────────┬──────────────────────────────────┘
                                │ ambos compartilham
┌───────────────────────────────▼──────────────────────────────────┐
│                   🧱 AS BASES DO ECOSSISTEMA                     │
│  • TL.BaseContracts (Result Pattern funcional e contratos base)   │
│  • TL.*ExtensionsLibrary (DateTime, Claims, Enum, Numeric)       │
│  • TL.MiddlewareLibrary (ProblemDetails padronizado e Rate Limit)│
│  • TL.HealthCheck (Probes de /livez e /readyz padronizados)      │
└──────────────────────────────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

Seja em uma Minimal API de 35MB ou em um microsserviço com Outbox no RabbitMQ:

  • O retorno de erros usa exatamente o mesmo Result<T> e ErrorType;
  • A extração de claims JWT usa a mesma TL.ClaimsPrincipalExtensionsLibrary;
  • A resposta de erro HTTP segue rigorosamente o mesmo formato estruturado (ProblemDetails);
  • A imagem base de container é a mesma (aspnet:9.0-noble-chiseled, não-root e sem shell).

A curva de aprendizado da equipe cai drasticamente, e a manutenção do ecossistema se torna previsível.


💡 3 Reflexões Práticas de Arquitetura

  1. Fuja do "modelo único para tudo": Padronização técnica não significa forçar todos os problemas a caberem no mesmo molde. Estabelecer modelos bem definidos para diferentes perfis de carga e criticidade evita desperdício de tempo e recursos.
  2. Cuidado com a complexidade acidental: Quando usamos uma arquitetura pesada para resolver um problema simples, a complexidade que o time passa a gerenciar não é a do negócio; é a que nós mesmos introduzimos no sistema.
  3. Clareza de critérios compartilhada com o time: Compartilhar a matriz de decisão com os desenvolvedores dá autonomia técnica à equipe. Quando qualquer desenvolvedor consegue justificar a escolha da arquitetura com base em métricas de boot, consumo de memória e garantias transacionais, a maturidade de engenharia dá um salto real.

Como Instalar e Testar Localmente

Ambos os templates estão disponíveis publicamente via .NET CLI:

# 1. Instalação dos templates oficiais
dotnet new install TL.LiteCore.Template
dotnet new install TL.ResilientCore.Template

# 2. Criar uma Minimal API leve (TL.LiteCore)
dotnet new tl-litecore -n MinhaOrganizacao.CatalogoApi

# 3. Criar um Microsserviço Resiliente com Outbox (TL.ResilientCore)
dotnet new tl-resilientcore -n MinhaOrganizacao.PagamentosApi
Enter fullscreen mode Exit fullscreen mode

Na sua organização, como os times decidem qual arquitetura usar em um novo serviço? Vocês usam um modelo único para tudo ou diferenciam APIs simples de sistemas críticos orientados a eventos? Compartilhe nos comentários!

Top comments (0)