Forem: Lincoln Zocateli

Gargalo em Banco de Dados: Mensageria e Paginação

Lincoln Zocateli — Thu, 16 Apr 2026 01:10:49 +0000

Introdução

Todo desenvolvedor .NET que trabalha com aplicações de médio ou grande porte já esbarrou em pelo menos um destes cenários: uma rotina noturna que precisa gravar 50 mil pedidos no banco, uma consulta de relatório que traz 300 mil registros de uma única vez e trava a aplicação, ou uma API que demora 8 segundos para responder porque o EF Core está executando 10 mil INSERT individuais em sequência.

O SQL Server e o Oracle são bancos robustos e maduros, mas nenhum deles foi projetado para receber milhares de gravações em rajada, nem para retornar centenas de milhares de linhas de uma só vez sem custo. O problema, na maioria dos casos, não é o banco — é a forma como a aplicação C# interage com ele.

Neste artigo vamos explorar as duas faces do gargalo: escrita em massa e leitura de grandes volumes. Para cada uma, você vai ver a causa raiz, as particularidades de SQL Server e Oracle com EF Core 8.0+, e a solução prática — mensageria para gravação e paginação eficiente para leitura. Todo o código é produção-ready e compatível com .NET 8/9.

Pré-requisitos: Conhecimento básico de C# e EF Core. Recomenda-se ter lido o artigo sobre programação assíncrona com C# antes de continuar.

📦 Código-fonte: A implementação completa deste artigo está no repositório blog-zocateli-sample no GitHub. Clone, explore e adapte ao seu contexto.

O Gargalo de Escrita: Por Que Gravar Milhares de Registros Dói

O Custo Real de Cada INSERT

Quando você salva uma lista de entidades com o EF Core da forma mais comum, algo assim acontece:

// ❌ Abordagem ingênua — InsertOne por vez
foreach (var pedido in listaDe50MilPedidos)
{
    await context.Pedidos.AddAsync(pedido);
    await context.SaveChangesAsync(); // PROBLEMA: 1 roundtrip por registro!
}

Cada SaveChangesAsync() dentro do loop representa:

Uma transação aberta → commit → fechada no banco
Um roundtrip de rede (latência de 1–5ms por chamada)
Log do banco de dados sendo escrito para cada operação
Locks de linha sendo alocados e liberados 50 mil vezes Para 50.000 pedidos com 2ms de latência por roundtrip, isso representa 100 segundos de processamento puro de I/O. E isso é no melhor cenário, sem contenção.

Particularidades: SQL Server vs Oracle

Ainda que a solução seja similar nos dois bancos, há diferenças importantes:

Aspecto	SQL Server	Oracle
Bulk Insert nativo	BULK INSERT / SqlBulkCopy	ODP.NET BulkCopy / INSERT ALL
Tamanho máximo de lote padrão	1.000 linhas por INSERT	Depende do ArrayBindCount
Sequências / Identity	IDENTITY ou SEQUENCE	Apenas SEQUENCE (obrigatório)
Rollback de bulk	Pode ser minimamente logado	Sempre logado (redo log)
EF Core provider	Microsoft.EntityFrameworkCore.SqlServer	Oracle.EntityFrameworkCore

No Oracle, um detalhe crítico é que o provider oficial (Oracle.EntityFrameworkCore 8.x) exige que você configure a geração de chaves via SEQUENCE + TRIGGER (ou GENERATED ALWAYS AS IDENTITY no Oracle 12c+). Ignorar isso em gravações em massa vai gerar N chamadas extras ao banco só para obter os IDs.

// Oracle: configuração correta no OnModelCreating
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Pedido>(entity =>
    {
        entity.HasKey(e => e.Id);

        // Oracle 12c+: identity nativo, evita roundtrip extra por ID
        entity.Property(e => e.Id)
              .UseIdentityColumn();

        // Alternativa para Oracle 11g/legado
        // entity.Property(e => e.Id)
        //       .HasDefaultValueSql("SEQ_PEDIDOS.NEXTVAL");
    });
}

A Solução Imediata: SaveChanges em Lote com EF Core 8

Antes de introduzir filas, a primeira otimização é mover o SaveChangesAsync() para fora do loop e usar o chunk para não sobrecarregar o contexto:

// ✅ Melhor: batch por chunk + 1 SaveChanges por lote
public async Task GravarPedidosEmLoteAsync(
    IEnumerable<Pedido> pedidos,
    CancellationToken ct = default)
{
    const int tamanhoLote = 500;

    foreach (var chunk in pedidos.Chunk(tamanhoLote))
    {
        await context.Pedidos.AddRangeAsync(chunk, ct);
        await context.SaveChangesAsync(ct);

        // Limpar o ChangeTracker para não acumular entidades em memória
        context.ChangeTracker.Clear();
    }
}

💡 Dica: O método Chunk() foi introduzido no .NET 6. Combinado com ChangeTracker.Clear(), evita que o contexto EF Core cresça indefinidamente ao rastrear dezenas de milhares de entidades.

ExecuteInsertAsync e BulkInsert no EF Core 8

O EF Core 7 trouxe ExecuteUpdateAsync e ExecuteDeleteAsync. O EF Core 8 melhorou o suporte a operações em massa. Para cenários de altíssima performance, use a biblioteca EFCore.BulkExtensions:

// ✅ BulkInsert para SQL Server e Oracle (via EFCore.BulkExtensions)
// dotnet add package EFCore.BulkExtensions
public async Task BulkInsertPedidosAsync(
    List<Pedido> pedidos,
    CancellationToken ct = default)
{
    var bulkConfig = new BulkConfig
    {
        BatchSize = 1000,
        UseTempDB = true,              // SQL Server: tabela temporária para staging
        SetOutputIdentity = true,      // Preenche os IDs gerados pelo banco
        PreserveInsertOrder = true
    };

    await context.BulkInsertAsync(pedidos, bulkConfig, cancellationToken: ct);
}

Com BulkInsert, 50.000 registros que levavam 100 segundos com SaveChanges individual passam a ser gravados em 2–4 segundos no SQL Server, e em 3–6 segundos no Oracle.

Mensageria: A Solução Arquitetural para Gravação em Massa

Otimizar o próprio INSERT resolve o sintoma, mas não a causa raiz. O problema real é que a aplicação está tentando processar um volume enorme de forma síncrona, bloqueando a thread e a requisição enquanto grava. A solução arquitetural correta é desacoplar a recepção da gravação usando uma fila de mensagens.

Como a Mensageria Resolve o Problema

Em vez de gravar diretamente no banco ao receber os dados, a aplicação:

Publica os registros em uma fila (RabbitMQ, Azure Service Bus, etc.) — operação rápida (~1ms por mensagem)
Retorna imediatamente para o cliente com 202 Accepted
Um Consumer separado lê a fila em lotes e grava no banco com bulk insert

Essa separação traz benefícios além da performance:

Resiliência: se o banco cair temporariamente, as mensagens ficam na fila. Naão há perda de dados.
Controle de fluxo: o consumer pode processar na velocidade que o banco suporta
Backpressure natural: a fila amortece picos de carga
Observabilidade: você pode monitorar o tamanho da fila e saber exatamente o backlog pendente

Implementação com RabbitMQ.Client

A biblioteca oficial RabbitMQ.Client é 100% open-source (Apache 2.0) e fornece acesso direto ao protocolo AMQP. Combinada com o BackgroundService do .NET, implementamos um consumer que acumula mensagens em lote e grava tudo de uma vez com BulkInsert.

// dotnet add package RabbitMQ.Client
// dotnet add package EFCore.BulkExtensions

// --- Mensagem ---
public record PedidoCriadoMessage(
    Guid Id,
    string ClienteId,
    decimal Valor,
    DateTime DataCriacao);

// --- Producer ---
public class PedidoProducer(IConnection connection)
{
    private const string QueueName = "pedidos-queue";

    public async Task PublicarAsync(
        PedidoCriadoMessage mensagem,
        CancellationToken ct = default)
    {
        await using var channel = await connection.CreateChannelAsync(cancellationToken: ct);

        await channel.QueueDeclareAsync(
            queue: QueueName,
            durable: true,
            exclusive: false,
            autoDelete: false,
            cancellationToken: ct);

        var json = JsonSerializer.SerializeToUtf8Bytes(mensagem);
        var props = new BasicProperties { DeliveryMode = DeliveryModes.Persistent };

        await channel.BasicPublishAsync(
            exchange: string.Empty,
            routingKey: QueueName,
            mandatory: false,
            basicProperties: props,
            body: json,
            cancellationToken: ct);
    }
}

// --- Consumer em lote (BackgroundService) ---
public class PedidoConsumerWorker(
    IConnection connection,
    IServiceScopeFactory scopeFactory,
    ILogger<PedidoConsumerWorker> logger) : BackgroundService
{
    private const string QueueName = "pedidos-queue";
    private const int TamanhoLote = 500;

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        await using var channel = await connection.CreateChannelAsync(cancellationToken: ct);

        await channel.QueueDeclareAsync(
            queue: QueueName, durable: true,
            exclusive: false, autoDelete: false,
            cancellationToken: ct);

        // Backpressure: limita mensagens em voo para não sobrecarregar a memória
        await channel.BasicQosAsync(
            prefetchSize: 0,
            prefetchCount: TamanhoLote + 100,
            global: false,
            cancellationToken: ct);

        var lote = new List<(ulong Tag, PedidoCriadoMessage Msg)>();

        var consumer = new AsyncEventingBasicConsumer(channel);
        consumer.ReceivedAsync += async (_, ea) =>
        {
            var msg = JsonSerializer.Deserialize<PedidoCriadoMessage>(ea.Body.Span)!;
            lote.Add((ea.DeliveryTag, msg));

            if (lote.Count >= TamanhoLote)
                await ProcessarLoteAsync(channel, lote, ct);
        };

        await channel.BasicConsumeAsync(
            queue: QueueName,
            autoAck: false,
            consumer: consumer,
            cancellationToken: ct);

        // Timer de flush: força o processamento mesmo que o lote não esteja cheio
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(5));
        while (await timer.WaitForNextTickAsync(ct))
        {
            if (lote.Count > 0)
                await ProcessarLoteAsync(channel, lote, ct);
        }
    }

    private async Task ProcessarLoteAsync(
        IChannel channel,
        List<(ulong Tag, PedidoCriadoMessage Msg)> lote,
        CancellationToken ct)
    {
        var snapshot = lote.ToList();
        lote.Clear();

        var pedidos = snapshot.Select(x => new Pedido
        {
            Id           = x.Msg.Id,
            ClienteId    = x.Msg.ClienteId,
            Valor        = x.Msg.Valor,
            DataCriacao  = x.Msg.DataCriacao
        }).ToList();

        using var scope    = scopeFactory.CreateScope();
        var dbContext       = scope.ServiceProvider.GetRequiredService<AppDbContext>();
        var bulkConfig      = new BulkConfig { BatchSize = 500 };

        await dbContext.BulkInsertAsync(pedidos, bulkConfig, cancellationToken: ct);

        // ACK múltiplo: confirma todo o lote de uma só vez
        await channel.BasicAckAsync(
            deliveryTag: snapshot[^1].Tag,
            multiple: true,
            cancellationToken: ct);

        logger.LogInformation("Lote de {Count} pedidos gravado", pedidos.Count);
    }
}

Registrando no Program.cs

// Program.cs
// dotnet add package RabbitMQ.Client
builder.Services.AddSingleton<IConnection>(_ =>
{
    var factory = new ConnectionFactory
    {
        HostName = "localhost",
        UserName = "guest",
        Password = "guest"
    };
    // CreateConnectionAsync retorna Task — resolvemos aqui para o DI container
    return factory.CreateConnectionAsync().GetAwaiter().GetResult();
});

builder.Services.AddScoped<PedidoProducer>();
builder.Services.AddHostedService<PedidoConsumerWorker>();

⚠️ Atenção: No Oracle, o BulkInsert do EFCore.BulkExtensions requer o Oracle Data Provider for .NET (ODP.NET). Certifique-se de registrar o provider correto e de que as sequences foram configuradas corretamente no modelo, ou a inserção em massa vai falhar com erro de constraint de chave primária.

RabbitMQ vs Azure Service Bus: Qual Escolher?

As duas opções resolvem o mesmo problema — desacoplar produção e consumo de mensagens — mas com modelos operacionais e econômicos bem distintos. A escolha depende do seu contexto: infraestrutura self-hosted vs cloud managed, custo variável vs fixo, e grau de controle desejado.

Critério	RabbitMQ	Azure Service Bus
Tipo	Open-source (MPL 2.0), self-hosted	PaaS gerenciado pela Microsoft
Protocolo	AMQP 0-9-1 (nativo), AMQP 1.0, MQTT, STOMP	AMQP 1.0
Hospedagem	Container próprio, VM, Kubernetes	Azure (sem infra para gerenciar)
Custo	Infraestrutura + operação (seu time)	Pay-per-use (~$0,10/milhão de ops)
Filas	Queues, Exchanges, Bindings	Queues e Topics/Subscriptions
Tamanho máximo de mensagem	128 MB (padrão)	256 KB (Standard) / 100 MB (Premium)
Retenção de mensagens	Até o disco encher / TTL configurável	14 dias (máximo)
Dead-letter queue	✅ Configurável	✅ Nativo
Sessions (ordenação garantida)	✅ Via x-single-active-consumer	✅ Service Bus Sessions
Retry automático	Manual (Dead-letter + requeue)	Nativo (MaxDeliveryCount)
Escalabilidade horizontal	Manual (cluster Erlang)	Automática
Biblioteca .NET	RabbitMQ.Client (Apache 2.0)	Azure.Messaging.ServiceBus (MIT)
Melhor para	On-premise, multi-cloud, custo controlado	Ecossistema Azure, equipe pequena, SLA garantido

Implementação Equivalente com Azure Service Bus

Para migrar do RabbitMQ para o Azure Service Bus em ambiente Azure, o padrão de producer/consumer é similar, usando Azure.Messaging.ServiceBus:

// dotnet add package Azure.Messaging.ServiceBus

// --- Producer com envio em lote nativo ---
public class PedidoServiceBusProducer(ServiceBusSender sender)
{
    public async Task PublicarLoteAsync(
        IEnumerable<PedidoCriadoMessage> mensagens,
        CancellationToken ct = default)
    {
        // O ServiceBusMessageBatch respeita o limite de tamanho automaticamente
        using var batch = await sender.CreateMessageBatchAsync(ct);

        foreach (var msg in mensagens)
        {
            var sbMsg = new ServiceBusMessage(
                BinaryData.FromObjectAsJson(msg))
            {
                ContentType = "application/json",
                MessageId   = msg.Id.ToString()
            };

            if (!batch.TryAddMessage(sbMsg))
                throw new InvalidOperationException(
                    $"Mensagem {msg.Id} excede o limite do lote");
        }

        await sender.SendMessagesAsync(batch, ct);
    }
}

// --- Consumer com BackgroundService ---
public class PedidoServiceBusWorker(
    ServiceBusProcessor processor,
    IServiceScopeFactory scopeFactory,
    ILogger<PedidoServiceBusWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        processor.ProcessMessageAsync += async args =>
        {
            var msg = args.Message.Body
                          .ToObjectFromJson<PedidoCriadoMessage>();

            using var scope   = scopeFactory.CreateScope();
            var dbContext      = scope.ServiceProvider
                                      .GetRequiredService<AppDbContext>();
            var pedido         = new Pedido
            {
                Id          = msg.Id,
                ClienteId   = msg.ClienteId,
                Valor       = msg.Valor,
                DataCriacao = msg.DataCriacao
            };

            await dbContext.BulkInsertAsync(
                new List<Pedido> { pedido },
                cancellationToken: ct);

            // Confirma o processamento — remove da fila
            await args.CompleteMessageAsync(args.Message, ct);
        };

        processor.ProcessErrorAsync += args =>
        {
            logger.LogError(args.Exception,
                "Erro ao processar mensagem do Service Bus");
            return Task.CompletedTask;
        };

        await processor.StartProcessingAsync(ct);
        await Task.Delay(Timeout.Infinite, ct);
    }

    public override async Task StopAsync(CancellationToken ct)
    {
        await processor.StopProcessingAsync(ct);
        await base.StopAsync(ct);
    }
}

// Program.cs
builder.Services.AddSingleton(provider =>
{
    var client = new ServiceBusClient(
        "Endpoint=sb://meu-namespace.servicebus.windows.net/;...");
    return client.CreateSender("pedidos-queue");
});

builder.Services.AddSingleton(provider =>
{
    var client = new ServiceBusClient(
        "Endpoint=sb://meu-namespace.servicebus.windows.net/;...");
    return client.CreateProcessor("pedidos-queue", new ServiceBusProcessorOptions
    {
        MaxConcurrentCalls   = 4,   // Paralelismo no consumer
        AutoCompleteMessages = false // Controle manual de ACK
    });
});

builder.Services.AddHostedService<PedidoServiceBusWorker>();

💡 Dica: Em produção no Azure, prefira autenticação via Managed Identity em vez de connection string, usando new ServiceBusClient("meu-namespace.servicebus.windows.net", new DefaultAzureCredential()). Isso elimina segredos na configuração.

O Gargalo de Leitura: Por Que Trazer Tudo de Uma Vez é Perigoso

O Problema da Query Sem Limite

// ❌ NUNCA faça isso em produção com tabelas grandes
var todosPedidos = await context.Pedidos
    .Include(p => p.Itens)
    .Include(p => p.Cliente)
    .ToListAsync(); // Pode trazer 500 mil registros para a memória!

Essa query aparentemente inocente pode:

Consumir gigabytes de RAM no servidor da aplicação
Bloquear o banco com um table scan de longa duração
Gerar timeouts em ambientes com alta concorrência
Saturar a rede entre aplicação e banco com tráfego desnecessário
Travar o GC do .NET com objetos grandes que precisam ir para o LOH (Large Object Heap) No Oracle, um aspecto adicional é o uso do ROWNUM (Oracle 11g) vs FETCH FIRST &mldr; ROWS ONLY (Oracle 12c+), que afeta como a paginação é expressa em SQL. O provider Oracle.EntityFrameworkCore abstrai isso, mas é importante entender o que está sendo gerado.

Tipos de Paginação: Offset vs Keyset (Cursor)

📖 Artigo dedicado: Para um guia completo sobre todas as estratégias de paginação (Offset, Keyset, Cursor Server-Side, Time-based e Token Opaco) com SQL Server, Oracle e PostgreSQL — incluindo código EF Core 8+ para cada combinação —, veja: Paginação em APIs REST com C# e EF Core 8: Todos os Tipos, Todos os Bancos. Esta seção apresenta os conceitos essenciais; o artigo linked aprofunda quando e por que usar cada abordagem.

Existem duas estratégias principais de paginação, e cada uma tem casos de uso distintos:

Característica	Offset Pagination	Keyset (Cursor) Pagination
SQL gerado	OFFSET N ROWS FETCH NEXT M	WHERE id > :lastId
Performance em páginas iniciais	✅ Rápida	✅ Rápida
Performance em páginas tardias	❌ Lenta (scan cresce)	✅ Constante
Suporte a salto de página	✅ Direto	❌ Apenas sequencial
Registros novos entre páginas	❌ Pode duplicar/omitir	✅ Consistente
Caso de uso ideal	UI com números de página	Scroll infinito / APIs

Paginação por Offset: Simples e Adequada para UIs

A paginação por offset é a mais familiar, e o EF Core a gera corretamente para SQL Server e Oracle:

// Modelo de request padronizado
public record PaginacaoRequest(int Pagina = 1, int TamanhoPagina = 20)
{
    // Garante limites seguros
    public int TamanhoSeguro => Math.Min(Math.Max(TamanhoPagina, 1), 100);
    public int OffsetSeguro  => (Math.Max(Pagina, 1) - 1) * TamanhoSeguro;
}

// Modelo de resposta padronizado
public record PaginaResultado<T>(
    IReadOnlyList<T> Dados,
    int PaginaAtual,
    int TamanhoPagina,
    long TotalRegistros,
    int TotalPaginas);

// Serviço de consulta paginada
public class PedidoQueryService(AppDbContext context)
{
    public async Task<PaginaResultado<PedidoResumoDto>> ListarPedidosAsync(
        PaginacaoRequest paginacao,
        string? clienteId = null,
        CancellationToken ct = default)
    {
        // Construir query base com filtros opcionais
        var query = context.Pedidos
            .AsNoTracking()           // Leitura: sempre AsNoTracking!
            .Where(p => clienteId == null || p.ClienteId == clienteId);

        // COUNT separado para o total (EF Core 8 otimiza isso)
        var total = await query.LongCountAsync(ct);

        // Dados da página
        var dados = await query
            .OrderBy(p => p.DataCriacao)   // Orderby obrigatório para paginação consistente
            .Skip(paginacao.OffsetSeguro)
            .Take(paginacao.TamanhoSeguro)
            .Select(p => new PedidoResumoDto(   // Projection: só os campos necessários
                p.Id,
                p.ClienteId,
                p.Valor,
                p.DataCriacao,
                p.Status))
            .ToListAsync(ct);

        return new PaginaResultado<PedidoResumoDto>(
            Dados: dados,
            PaginaAtual: paginacao.Pagina,
            TamanhoPagina: paginacao.TamanhoSeguro,
            TotalRegistros: total,
            TotalPaginas: (int)Math.Ceiling(total / (double)paginacao.TamanhoSeguro));
    }
}

💡 Dica: Sempre use .Select() com uma projection (DTO ou record), nunca retorne a entidade completa em queries de listagem. Isso reduz o volume de dados transferidos e evita o carregamento de navegações desnecessárias.

SQL Gerado: SQL Server vs Oracle

O EF Core 8 gera SQL correto e otimizado para ambos os bancos:

-- SQL Server (gerado pelo EF Core 8)
SELECT p.Id, p.ClienteId, p.Valor, p.DataCriacao, p.Status
FROM Pedidos AS p
WHERE p.ClienteId = N'cliente-123'
ORDER BY p.DataCriacao
OFFSET 40 ROWS FETCH NEXT 20 ROWS ONLY;

-- Oracle 12c+ (gerado pelo Oracle.EntityFrameworkCore 8)
SELECT p.Id, p.ClienteId, p.Valor, p.DataCriacao, p.Status
FROM Pedidos p
WHERE p.ClienteId = :clienteId_0
ORDER BY p.DataCriacao
OFFSET 40 ROWS FETCH NEXT 20 ROWS ONLY;

⚠️ Atenção: Para Oracle 11g (sem FETCH FIRST), o provider gera uma query com ROWNUM aninhado, que pode ter custo adicional em tabelas muito grandes. Considere migrar para Oracle 12c+ ou usar views materializadas para relatórios pesados.

Keyset Pagination: Alta Performance para Scroll Infinito e APIs

Quando o usuário navega para a página 500 de um resultado com 10 mil itens, o banco precisa fazer um scan de 10.000 linhas só para pular as primeiras 9.980. Com keyset pagination, você usa o valor da última linha buscada como ponto de partida da próxima consulta:

// Request com cursor (keyset)
public record KeysetRequest(
    Guid? UltimoId = null,
    DateTime? UltimaDataCriacao = null,
    int Limite = 20);

// Resultado com cursor para a próxima página
public record KeysetResultado<T>(
    IReadOnlyList<T> Dados,
    bool TemProximaPagina,
    Guid? ProximoCursorId,
    DateTime? ProximoCursorData);

public class PedidoKeysetService(AppDbContext context)
{
    public async Task<KeysetResultado<PedidoResumoDto>> ListarComCursorAsync(
        KeysetRequest request,
        CancellationToken ct = default)
    {
        // Filtro de keyset: busca registros "após" o cursor
        // Usando (DataCriacao, Id) como chave composta para estabilidade
        var query = context.Pedidos
            .AsNoTracking()
            .Where(p =>
                request.UltimaDataCriacao == null ||
                p.DataCriacao > request.UltimaDataCriacao ||
                (p.DataCriacao == request.UltimaDataCriacao &&
                 p.Id.CompareTo(request.UltimoId!.Value) > 0))
            .OrderBy(p => p.DataCriacao)
            .ThenBy(p => p.Id);

        // Busca Limite + 1 para saber se há próxima página
        var dados = await query
            .Take(request.Limite + 1)
            .Select(p => new PedidoResumoDto(p.Id, p.ClienteId, p.Valor, p.DataCriacao, p.Status))
            .ToListAsync(ct);

        var temProxima = dados.Count > request.Limite;
        if (temProxima) dados.RemoveAt(dados.Count - 1); // Remove o item extra

        var ultimo = dados.LastOrDefault();

        return new KeysetResultado<PedidoResumoDto>(
            Dados: dados,
            TemProximaPagina: temProxima,
            ProximoCursorId: ultimo?.Id,
            ProximoCursorData: ultimo?.DataCriacao);
    }
}

Este padrão mantém performance constante independente do número da página, pois o SQL gerado usa um simples WHERE com índice em vez de OFFSET.

-- SQL gerado (SQL Server / Oracle)
SELECT TOP(21) p.Id, p.ClienteId, p.Valor, p.DataCriacao, p.Status
FROM Pedidos AS p
WHERE p.DataCriacao > '2025-06-01'
   OR (p.DataCriacao = '2025-06-01' AND p.Id > 'abc-123')
ORDER BY p.DataCriacao, p.Id;

💡 Dica: Crie um índice composto nas colunas de keyset para garantir que a query use index seek em vez de table scan:

-- SQL Server
CREATE INDEX IX_Pedidos_Keyset ON Pedidos (DataCriacao, Id) INCLUDE (ClienteId, Valor, Status);

-- Oracle
CREATE INDEX IX_Pedidos_Keyset ON Pedidos (DataCriacao, Id);

Juntando Tudo: A Arquitetura Completa

Com as duas soluções combinadas, a arquitetura da aplicação fica assim:

Escrita: API recebe → publica na fila → retorna 202 Accepted → Consumer processa em lote com BulkInsert
Leitura: API recebe request paginado → executa query com Skip/Take (offset) ou WHERE (keyset) → retorna somente os dados necessários

// Endpoint ASP.NET Core — escrita assíncrona
app.MapPost("/pedidos/lote", async (
    [FromBody] List<CriarPedidoRequest> requests,
    PedidoService service,
    CancellationToken ct) =>
{
    var ids = await Task.WhenAll(
        requests.Select(r => service.CriarPedidoAsync(r, ct)));

    // 202 Accepted: os pedidos foram enfileirados, não necessariamente gravados
    return Results.Accepted("/pedidos/status", new { Ids = ids });
});

// Endpoint ASP.NET Core — leitura paginada
app.MapGet("/pedidos", async (
    [AsParameters] PaginacaoRequest paginacao,
    [FromQuery] string? clienteId,
    PedidoQueryService queryService,
    CancellationToken ct) =>
{
    var resultado = await queryService.ListarPedidosAsync(paginacao, clienteId, ct);
    return Results.Ok(resultado);
});

Dicas e Boas Práticas

Índices adequados: Toda coluna usada em OrderBy, Where ou keyset cursor deve ter índice. No Oracle, use índices funcionais para colunas com transformações (ex.: UPPER(nome)).
AsNoTracking sempre em leituras: Desativa o Change Tracker para queries de leitura, reduzindo uso de memória e CPU em até 30%.
Evite Count() em tabelas grandes: Para keyset pagination, você não precisa do total de registros. Para offset, considere cachear o total por alguns segundos.
Defina timeouts explícitos: Configure context.Database.SetCommandTimeout(30) ou use WithTimeout por consulta para evitar queries longas bloqueando a aplicação indefinidamente.
Monitore o tamanho da fila: Configure alertas para quando a fila ultrapassar N mensagens — é o sinal de que o consumer não está dando conta do volume.
Use IAsyncEnumerable para streaming: Para exportações de CSV ou processamento de grandes volumes que não precisam de paginação, use AsAsyncEnumerable() para processar linha por linha sem carregar tudo na memória:

// Streaming com IAsyncEnumerable — sem carregar tudo na memória
await foreach (var pedido in context.Pedidos
    .AsNoTracking()
    .AsAsyncEnumerable()
    .WithCancellation(ct))
{
    await exportador.EscreverLinhaAsync(pedido, ct);
}

Transações explícitas para consistência: Ao usar BulkInsert com múltiplas tabelas (ex.: gravar Pedido e ItensPedido em conjunto), envolva a operação em uma transação explícita para garantir atomicidade.

Conclusão

Os gargalos de banco de dados com EF Core raramente são culpa do banco em si. Na esmagadora maioria dos casos, o problema está na forma como a aplicação interage com ele: inserindo um registro por vez em vez de em lote, e trazendo todo o resultado em vez de paginar.

A combinação de mensageria (RabbitMQ ou Azure Service Bus) para desacoplar gravação em massa e paginação eficiente (offset para UIs, keyset para APIs e scroll infinito) resolve os dois gargalos de forma elegante, escalável e resiliente. Com EF Core 8.0+ e as técnicas apresentadas aqui, você consegue suportar volumes muito maiores sem mudar a estrutura do banco, apenas ajustando a forma como a aplicação se comunica com ele.

O próximo passo natural é observabilidade: instrumentar as queries lentas com Application Performance Monitoring (APM), criar alertas para queries acima de N segundos, e mapear os índices faltantes via Query Store (SQL Server) ou AWR (Oracle).

Referências

EF Core — Bulk Operations (Microsoft Docs) — Estratégias oficiais de atualização eficiente com EF Core
EFCore.BulkExtensions — GitHub — Biblioteca open-source para bulk insert/update/delete no EF Core
RabbitMQ.Client — NuGet / GitHub — Biblioteca oficial .NET para RabbitMQ (Apache 2.0)
Azure.Messaging.ServiceBus — Documentação — Guia oficial do Azure Service Bus com .NET
RabbitMQ vs Azure Service Bus — Comparativo — Visão geral do Azure Service Bus e quando usá-lo
Oracle EF Core Provider — GitHub — Exemplos oficiais do provider Oracle para EF Core
Use the query store (SQL Server) — Monitoramento de queries lentas no SQL Server via Query Store
Repositório blog-zocateli-sample — Messaging — Código-fonte completo dos exemplos deste artigo 📬

👉 Artigo completo com todos os exemplos de código: Gargalo em Banco de Dados: Mensageria e Paginação

pip É Lento, Poetry Complexo: UV Chegou Resolvendo o Python

Lincoln Zocateli — Thu, 16 Apr 2026 01:00:50 +0000

Introdução

Se você já trabalhou com Python por mais de cinco minutos, provavelmente já viveu esse ritual: criar um ambiente virtual com venv, instalar pacotes com pip, descobrir que precisa do pip-tools para gerar um lockfile, usar pyenv para trocar de versão do Python, considerar o Poetry mas desistir da complexidade, e eventualmente aceitar que o gerenciamento de dependências em Python é um exercício de paciência.

O ecossistema Python sempre foi assim — poderoso, mas fragmentado. Cada ferramenta resolve um pedaço do problema. Nenhuma resolve tudo. E o desenvolvedor fica no meio, colando peças como um quebra-cabeça infinito.

Isso mudou. Em fevereiro de 2024, a Astral — a mesma empresa por trás do Ruff, o linter Python mais rápido do mundo — lançou o UV: um gerenciador de pacotes, ambientes virtuais e versões do Python escrito em Rust, até 100 vezes mais rápido que o pip. E ele não veio para ser mais uma peça do quebra-cabeça. Ele veio para ser o quebra-cabeça inteiro.

Neste artigo, vamos explorar:

A história do Python — quem criou, quando, e quem mantém hoje
Por que Python ganhou tanta notoriedade nos últimos anos
O problema de fragmentação que o UV resolve
O que é o UV, quem criou, e como usá-lo na prática
E a pergunta que não cala: em aplicações complexas, com padrões arquiteturais e modularidade, Python compete com C#? Se você já usa Python ou está avaliando se deve usá-lo, este artigo é para você.

Python: Uma Breve História

Origens

O Python foi criado por Guido van Rossum, um programador holandês que trabalhava no CWI (Centrum Wiskunde & Informatica) em Amsterdã. O desenvolvimento começou no final de 1989, e a primeira versão pública — Python 0.9.0 — foi lançada em fevereiro de 1991.

O nome não tem nada a ver com cobras. Guido era fã do grupo de comédia britânico Monty Python, e queria um nome curto, misterioso e levemente irreverente. Funcionou.

Filosofia

Desde o início, Python foi projetado com uma filosofia clara: legibilidade acima de tudo. Onde outras linguagens usam chaves {} e ponto-e-vírgula ;, Python usa indentação. A ideia era que o código deveria ser tão fácil de ler quanto de escrever.

Essa filosofia foi formalizada no Zen of Python (PEP 20), que você pode ver rodando import this no interpretador:

import this

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Readability counts.
There should be one -- and preferably only one -- obvious way to do it.

💡 O Zen of Python não é apenas poesia — ele guia decisões de design da linguagem até hoje.

Guido e o BDFL

Por quase três décadas, Guido atuou como BDFL — Benevolent Dictator For Life (Ditador Benevolente Vitalício). Ele tinha a palavra final sobre qualquer decisão de design da linguagem.

Isso mudou em julho de 2018, quando a controversa PEP 572 (que introduziu o operador :=, apelidado de walrus operator) gerou debates tão intensos na comunidade que Guido decidiu se afastar. Ele renunciou ao título de BDFL e se aposentou da liderança direta.

Quem mantém Python hoje

Desde 2019, Python é governado por um Steering Council — um comitê eleito de cinco membros que toma as decisões de design e direção da linguagem. O conselho é eleito pela comunidade de core developers a cada release. Por trás do Steering Council está a Python Software Foundation (PSF), uma organização sem fins lucrativos que cuida da infraestrutura, eventos, financiamento e proteção da marca Python.

ℹ️ Guido van Rossum trabalhou na Dropbox (2013–2019) e depois na Microsoft (2020–2023), onde contribuiu significativamente para a performance do CPython (o interpretador padrão). Hoje segue como core developer emeritus, mas sem poder de veto.

Versões marcantes

Ano	Versão	Marco
1991	0.9.0	Primeira versão pública
2000	2.0	List comprehensions, garbage collector
2008	3.0	Quebra de compatibilidade com Python 2 (migração dolorosa que durou mais de uma década)
2015	3.5	async/await nativo, type hints (PEP 484)
2016	3.6	f-strings (f"Hello {name}") — mudou a forma de formatar strings para sempre
2020	3.9	Merge de dicionários com
2022	3.11	Melhorias de performance de 10-60% (projeto Faster CPython de Guido na Microsoft)
2023	3.12	Per-interpreter GIL (início do caminho para remover o GIL)
2024	3.13	Free-threaded mode experimental (sem GIL)

⚠️ A migração de Python 2 para Python 3 foi uma das mais dolorosas da história da computação. Levou mais de 12 anos — Python 2 só teve seu EOL (End of Life) em janeiro de 2020. Essa experiência traumática moldou a comunidade: desde então, Python evita quebras de compatibilidade a todo custo.

Por Que Python Ganhou Tanta Notoriedade

Se em 2010 alguém te dissesse que Python seria a linguagem mais popular do mundo em poucos anos, você provavelmente duvidaria. Naquela época, o reinado era de Java, C e C++. Python era visto como linguagem de script, boa para automação e pouco mais. O que mudou?

A revolução dos dados e da IA

A ascensão da ciência de dados, do machine learning e da inteligência artificial colocou Python no centro do mapa. Não porque Python fosse a linguagem mais rápida ou mais robusta — mas porque o ecossistema se formou ao redor dela:

Área	Bibliotecas Python dominantes
Computação numérica	NumPy, SciPy
Análise de dados	Pandas, Polars
Machine Learning	scikit-learn, XGBoost, LightGBM
Deep Learning	TensorFlow, PyTorch, Keras
IA Generativa	LangChain, Hugging Face Transformers, OpenAI SDK
Visualização	Matplotlib, Seaborn, Plotly
Notebooks	Jupyter, Google Colab

Quando TensorFlow (Google, 2015) e PyTorch (Meta, 2016) escolheram Python como interface principal, o destino estava selado. Pesquisadores, cientistas de dados e engenheiros de ML se concentraram em Python, e o efeito de rede fez o resto.

Adoção acadêmica

Universidades no mundo inteiro passaram a ensinar programação com Python em vez de Java ou C. O MIT trocou seu curso introdutório para Python em 2009. Stanford seguiu. A consequência: uma geração inteira de desenvolvedores cresceu com Python como primeira linguagem.

Versatilidade

Python não é apenas para IA. Ele tem presença relevante em:

Web: Django (full-stack), FastAPI (APIs modernas), Flask (microframework)
Automação e DevOps: Ansible, scripts de infraestrutura, CI/CD
Scripting: substituição de Bash para tarefas complexas
APIs e microsserviços: com FastAPI + Pydantic
Educação: pela sintaxe limpa e barreira de entrada baixa

Python em números (2025–2026)

Indicador	Posição / Métrica
TIOBE Index	#1 (líder desde 2021)
Stack Overflow Survey 2025	Top 3 linguagens mais usadas
GitHub Octoverse 2025	#1 em novos repositórios
PyPI (repositório oficial)	600.000+ pacotes publicados
Downloads mensais (PyPI)	15+ bilhões

💡 Python não é necessariamente a melhor linguagem para cada problema. Mas é a linguagem com o menor atrito para começar — e isso conta muito quando o objetivo é validar ideias, prototipar ou iterar rapidamente.

O Problema Que UV Resolve

Agora que entendemos por que Python é tão popular, vamos ao ponto que todo desenvolvedor Python conhece bem: o caos do gerenciamento de pacotes e ambientes.

O ecossistema antes do UV

A história do gerenciamento de dependências em Python é uma história de fragmentação. Cada ferramenta resolve um pedaço do problema, mas nenhuma resolve tudo:

Ferramenta	O que faz	O que NÃO faz	Problema
pip	Instala pacotes	Não gerencia ambientes, não faz lockfile nativo	Lento (resolução em Python puro), sem reprodutibilidade
virtualenv / venv	Cria ambientes virtuais	Não instala pacotes, não gerencia versões do Python	É apenas uma peça do quebra-cabeça
pip-tools	Gera lockfile (requirements.txt pinado)	Não gerencia ambientes nem versões do Python	Exige combinação manual com pip + venv
Pipenv	Combina pip + virtualenv + lockfile	Performance ruim, manutenção instável	Praticamente abandonado pela comunidade
Poetry	Gerencia pacotes, venv, lockfile, build	Não gerencia versões do Python	Complexo, lento, resolve tudo mas com custo
Conda	Gerencia pacotes + ambientes + Python + C/Fortran	Mundo paralelo ao PyPI	Conflitos com pip, ecossistema isolado
pyenv	Gerencia versões do Python	Não instala pacotes, não gerencia ambientes	Mais uma ferramenta para aprender
pipx	Executa ferramentas Python isoladas	Não é para projetos	Escopo limitado

O fluxo típico antes do UV

Para montar um projeto Python “direito” antes do UV, o desenvolvedor precisava combinara múltiplas ferramentas:

# ❌ Fluxo fragmentado (antes do UV)

# 1. Instalar a versão certa do Python
pyenv install 3.12.1
pyenv local 3.12.1

# 2. Criar ambiente virtual
python -m venv .venv
source .venv/bin/activate    # Linux/macOS
# .venv\Scripts\Activate.ps1 # Windows

# 3. Instalar dependências
pip install fastapi uvicorn

# 4. Gerar lockfile (se usando pip-tools)
pip install pip-tools
pip-compile requirements.in -o requirements.txt

# 5. Executar ferramentas de linting (se usando pipx)
pipx install ruff
ruff check .

Cinco ferramentas diferentes. Cinco comandos de instalação. Cinco coisas para documentar e explicar para quem chega no projeto. Esse é o problema que o UV resolve.

⚠️ O Poetry tentou unificar parte desse fluxo, e para muitos projetos funciona bem. Mas a resolução de dependências é lenta (escrita em Python), o pyproject.toml tem convenções próprias que divergem dos padrões PEP, e ele ainda exige pyenv separado para gerenciar versões do Python.

UV: O Que É e Quem Criou

A Astral e Charlie Marsh

O UV foi criado pela Astral, uma empresa fundada por Charlie Marsh em 2023. Charlie é um engenheiro de software americano que antes de fundar a Astral trabalhava com infraestrutura Python e percebeu que as ferramentas fundamentais do ecossistema estavam décadas atrás do que outras linguagens ofereciam.

A Astral já era conhecida pelo Ruff — um linter e formatter para Python escrito em Rust que é 100 a 300 vezes mais rápido que ferramentas equivalentes como Flake8 e Black. O sucesso do Ruff provou que reescrever tooling Python em Rust gerava ganhos reais e imensos.

Em fevereiro de 2024, a Astral lançou o UV com a mesma premissa: pegar o que o ecossistema Python fazia de forma lenta e fragmentada e reescrever em Rust, rápido e unificado.

💡 A Astral recebeu investimento de US$ 4 milhões da Accel para desenvolver o UV e o Ruff. Charlie Marsh é ex-engenheiro do Spring Health e do Khan Academy.

O que o UV faz

O UV é um toolkit unificado para Python, escrito em Rust. Ele substitui — sozinho — as seguintes ferramentas:

┌─────────────────────────────────────────────────────────┐
│                         UV                              │
│                                                         │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│   │ Gerenciador  │  │  Ambientes   │  │  Versões do  │  │
│   │ de pacotes   │  │  virtuais    │  │  Python      │  │
│   │ (pip,        │  │ (virtualenv, │  │ (pyenv)      │  │
│   │  pip-tools)  │  │  venv)       │  │              │  │
│   └──────────────┘  └──────────────┘  └──────────────┘  │
│                                                         │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│   │ Gerenciador  │  │  Execução    │  │  Lockfile    │  │
│   │ de projetos  │  │  de scripts  │  │  nativo      │  │
│   │ (poetry)     │  │  e tools     │  │  (uv.lock)   │  │
│   │              │  │  (pipx)      │  │              │  │
│   └──────────────┘  └──────────────┘  └──────────────┘  │
│                                                         │
└─────────────────────────────────────────────────────────┘

Em termos concretos:

Capacidade	Ferramenta que substitui	Comando UV
Instalar pacotes	pip install	uv add / uv pip install
Criar ambiente virtual	python -m venv	uv venv (automático)
Gerar lockfile	pip-compile (pip-tools)	uv lock (automático)
Gerenciar versões do Python	pyenv install	uv python install
Criar projeto	poetry init	uv init
Executar ferramentas	pipx run	uvx
Executar scripts	python script.py	uv run script.py

Velocidade

A diferença de velocidade não é incremental — é de outra ordem de grandeza:

Operação	pip	UV	Fator
Instalar dependências (cache frio)	~22s	~1.2s	18x mais rápido
Instalar dependências (cache quente)	~5s	~0.06s	80x mais rápido
Resolução de dependências	segundos a minutos	milissegundos	10-100x mais rápido
Criar ambiente virtual	~1.5s	~0.01s	150x mais rápido

📌 Esses números variam conforme o projeto e o ambiente, mas a ordem de grandeza é consistente. O UV faz em milissegundos o que o pip faz em segundos — e em segundos o que o pip faz em minutos.

Essa velocidade não é acidente. O UV é escrito em Rust, com resolução de dependências implementada em um solver SAT otimizado (PubGrub), cache agressivo, downloads paralelos e zero overhead de interpretador Python.

UV na Prática

Chega de teoria. Vamos ver o UV funcionando.

Instalação

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Via pip (se preferir — mas perde parte da graça)
pip install uv

# Via Homebrew (macOS)
brew install uv

Após instalar, verifique:

uv --version

uv 0.6.x

Criar um projeto novo

uv init meu-projeto-api
cd meu-projeto-api

O UV gera a seguinte estrutura:

meu-projeto-api/
├── .python-version      # Versão do Python fixada
├── pyproject.toml        # Metadados e dependências do projeto
├── README.md
└── main.py               # Entrypoint básico

O pyproject.toml gerado segue os padrões PEP (621, 517):

[project]
name = "meu-projeto-api"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

💡 Diferente do Poetry, que usa chaves proprietárias como [tool.poetry], o UV segue os padrões PEP oficiais. Isso significa que seu pyproject.toml é compatível com qualquer ferramenta que siga as PEPs.

Adicionar dependências

# Adicionar dependências de produção
uv add fastapi uvicorn[standard]

# Adicionar dependências de desenvolvimento
uv add --dev pytest ruff mypy

O que acontece por baixo:

O UV atualiza o pyproject.toml com as novas dependências
Resolve todas as dependências (em milissegundos)
Gera/atualiza o uv.lock — um lockfile com hashes e versões exatas
Cria o ambiente virtual (.venv/) automaticamente, se não existir
Instala tudo no ambiente virtual Tudo em um único comando. Em menos de dois segundos.

Executar o projeto

# Executar diretamente (UV ativa o venv automaticamente)
uv run uvicorn main:app --reload

# Ou executar qualquer script Python
uv run python main.py

💡 Não precisa ativar o ambiente virtual manualmente. O uv run faz isso por você. Acabou o source .venv/bin/activate.

Gerenciar versões do Python

# Listar versões disponíveis
uv python list

# Instalar uma versão específica
uv python install 3.12

# Fixar a versão do projeto
uv python pin 3.12

O UV baixa e gerencia as versões do Python sem precisar do pyenv. Funciona em Windows, Linux e macOS.

Executar ferramentas sem instalar

# Executar o Ruff sem instalar no projeto
uvx ruff check .

# Executar o Black sem instalar
uvx black --check .

# Executar qualquer ferramenta do PyPI
uvx httpie https://api.github.com

O uvx é equivalente ao npx do Node.js — executa ferramentas Python em ambientes temporários, sem poluir seu projeto.

Fluxo completo com UV

Lembra do fluxo fragmentado com cinco ferramentas? Agora com UV:

# ✅ Fluxo unificado com UV

# 1. Criar projeto (já fixa a versão do Python)
uv init meu-projeto
cd meu-projeto

# 2. Instalar dependências (cria venv + lockfile automaticamente)
uv add fastapi uvicorn[standard]
uv add --dev pytest ruff

# 3. Executar (ativa venv automaticamente)
uv run uvicorn main:app --reload

# 4. Rodar testes
uv run pytest

# 5. Linting (sem instalar no projeto)
uvx ruff check .

Uma ferramenta. Cinco linhas. Zero fricção.

Quando Usar UV

Cenários ideais

O UV é a escolha certa quando você:

Está começando um projeto novo em Python — o uv init dá a estrutura padrão perfeita
Quer velocidade no CI/CD — instalar dependências em 1 segundo em vez de 30 faz diferença em pipelines
Trabalha com múltiplas versões do Python — uv python install substitui pyenv sem fricção
Quer reprodutibilidade — o uv.lock garante que todos no time usem exatamente as mesmas versões
Precisa de algo simples — um comando para tudo, sem configuração complexa
Mantém monorepos Python — o UV suporta workspaces no estilo Cargo/npm
Quer padronizar o toolchain — uma ferramenta para gerenciar tudo, de venv a lockfile

Cenários onde ainda avaliar

Cenário	Recomendação
Projetos com Conda/Anaconda	O UV não substitui Conda para dependências C/Fortran (BLAS, LAPACK, etc.). Se seu projeto depende pesadamente do ecossistema Conda, avalie a migração com cuidado
Projetos legados muito grandes	A migração de um projeto grande com Poetry ou Pipenv pode exigir ajustes. Funciona, mas teste em branches separados
Ambientes corporativos restritos	Se sua empresa bloqueia binários externos, o UV (que é um binário Rust) pode precisar de aprovação de segurança

💡 O UV é compatível com o pip. Você pode usar uv pip install -r requirements.txt como substituto direto do pip — mesma interface, velocidade de Rust. Essa é a forma mais segura de experimentar sem mudar nada no projeto.

Python vs C# em Aplicações Complexas

Essa é a pergunta que motivou metade deste artigo: quando a aplicação precisa ser modular, com padrões arquiteturais como Clean Architecture, CQRS, Hexagonal — vale a pena usar Python em vez de C#? Existe ganho real?

A resposta honesta é: depende do que você chama de “ganho”.

Comparativo completo

Dimensão	Python	C#
Tipagem	Dinâmica (com hints opcionais via mypy, Pydantic)	Estática forte (compilador garante)
Compilação	Interpretado — erros aparecem em runtime	Compilado — erros aparecem antes do deploy
Injeção de Dependência	Terceiros: dependency-injector, python-inject, manual	Nativa no framework (IServiceCollection)
Interfaces / Contratos	ABC (Abstract Base Class) — não é enforcement forte	interface — contrato real, verificado pelo compilador
Padrões Arquiteturais	Possível, mas exige disciplina manual. Sem framework opinativo para Clean Architecture	Ecossistema maduro: MediatR (CQRS), templates de Clean Architecture, Minimal APIs
ORM	SQLAlchemy, Django ORM, Tortoise	Entity Framework Core — superior em migrações, Fluent API e integração
Testes	pytest (excelente, maduro)	xUnit, NUnit, MSTest (todos maduros)
Performance	GIL limita paralelismo real (melhorando com 3.13+), I/O-bound é bom com asyncio	Paralelismo real, Tasks, async/await maduro, alta performance
Tooling / IDE	PyCharm, VS Code (bom, mas refactoring limitado pela tipagem dinâmica)	Visual Studio, Rider, VS Code (refactoring robusto com tipagem estática)
Ecossistema Enterprise	Azure SDK, AWS SDK — funcional, mas menos integrado	Azure nativo, ferramentas Microsoft integradas, ecossistema enterprise completo
Modularidade	Módulos e pacotes Python são flexíveis, mas não há enforcement de boundaries	Assemblies, namespaces, projetos separados com referências explícitas
Documentação / API	Swagger via FastAPI (automático), Sphinx	Swagger nativo, XML docs, source generators

Python para aplicações arquiteturais: é possível, mas&mldr;

Sim, você pode implementar Clean Architecture, Hexagonal, CQRS e qualquer padrão em Python. Frameworks como Django (opinativo, MTV) e FastAPI (moderno, async, Pydantic) oferecem bases sólidas. Existem bibliotecas para injeção de dependência, validação de tipos e separação de camadas.

Porém, há diferenças fundamentais na experiência de desenvolvimento:

# Python: Injeção de dependência com dependency-injector
from dependency_injector import containers, providers
from dependency_injector.wiring import Provide, inject

class Container(containers.DeclarativeContainer):
    config = providers.Configuration()
    user_repository = providers.Singleton(
        UserRepository,
        connection_string=config.db.connection_string,
    )
    user_service = providers.Factory(
        UserService,
        repository=user_repository,
    )

@inject
def create_user(
    service: UserService = Provide[Container.user_service],
):
    service.create(name="Lincoln")

// C#: Injeção de dependência nativa no .NET
builder.Services.AddScoped<IUserRepository, UserRepository>();
builder.Services.AddScoped<IUserService, UserService>();

// No controller ou endpoint, o framework injeta automaticamente
app.MapPost("/users", (IUserService service) =>
{
    service.Create(name: "Lincoln");
});

A diferença não é apenas de sintaxe — é de filosofia:

Em C#, a DI é parte do framework. Você não precisa escolher uma biblioteca, configurar wiring, ou decorar métodos. Funciona “out of the box”
Em Python, a DI é uma biblioteca terceira. Funciona, mas adiciona complexidade, exige configuração e não tem suporte nativo do framework Essa diferença se repete em quase todos os padrões:

Padrão	Em C#	Em Python
Interfaces	interface IService — contrato forte, verificado em compilação	class IService(ABC) — convenção, não enforcement real
Repository	Padrão maduro com EF Core, genéricos tipados	Implementável, mas sem tipo-segurança forte
CQRS	MediatR (biblioteca consagrada), separação clara	Implementação manual, sem biblioteca dominante
Mediator	MediatR	Sem equivalente consolidado
Options Pattern	IOptions nativo	Configuração manual ou Pydantic Settings

Onde Python vence — sem discussão

Há domínios onde Python simplesmente não tem concorrente real:

IA e Machine Learning: TensorFlow, PyTorch, Hugging Face — o ecossistema inteiro é Python-first
Ciência de dados: Pandas, NumPy, Jupyter — C# nem aparece na conversa
Prototipagem rápida: de zero a uma API funcional em minutos com FastAPI
Scripts e automação: substituir Bash, processar arquivos, interagir com APIs
DevOps: Ansible, scripts de infraestrutura, ferramentas CLI

Onde C# vence — quando complexidade importa

Para aplicações que exigem manutenção a longo prazo por equipes grandes, com padrões arquiteturais rigorosos, C# (e, de forma mais ampla, o .NET) oferece vantagens reais:

Refactoring seguro: tipagem estática forte permite renomear, extrair e mover código com confiança
Compilação como guardião: erros de tipo, interfaces não implementadas e dependências ausentes são detectados antes de executar qualquer código
DI e middleware nativos: o pipeline do ASP.NET Core é maduro, testável e extensível
Boundaries forçados: assemblies e projetos separados criam fronteiras arquiteturais reais, não apenas convenções
Ecossistema enterprise: integração nativa com Azure, SQL Server, Identity, e todo o ecossistema Microsoft

O veredicto

📌 Python e C# não são concorrentes — são complementares.

Cenário	Linguagem recomendada
IA, ML, Deep Learning	Python
Ciência de dados, análise	Python
Scripts, automação, DevOps	Python
Prototipagem rápida de APIs	Python (FastAPI)
Aplicações enterprise com padrões rigorosos	C# (.NET)
Clean Architecture, Hexagonal, CQRS	C# (ecossistema mais maduro)
Aplicações com equipes grandes e manutenção longa	C# (tipagem estática = segurança)
APIs de alta performance com I/O intensivo	C# (async/await maduro, Kestrel)
Microsserviços com orquestração complexa	Ambos (depende do ecossistema da empresa)

A pergunta certa não é “Python ou C#?” — é “qual problema estou resolvendo?”

Se o problema é IA, dados ou prototipagem: Python, sem pensar duas vezes.

Se o problema é uma aplicação modular, com camadas, padrões e equipe que precisa de refactoring seguro em dois anos: C# vai te dar menos dor de cabeça.

E se o problema exige os dois? Use os dois. Microsserviço de IA em Python, orquestração e API principal em C# — isso não é heresia, é pragmatismo.

Considerações Importantes

UV Ainda É Pré-1.0

O UV está em versão 0.6.x (março 2026). Apesar de estável para uso em produção e adotado por milhares de projetos, a versão pré-1.0 significa que breaking changes podem acontecer entre releases menores. A Astral mitiga isso com changelogs detalhados e migração assistida, mas é um ponto a considerar antes de adotar em ambientes corporativos conservadores. Acompanhe os releases no GitHub para saber quando a 1.0 chegar.

O `pyproject.toml` Como Fonte de Verdade

O UV adota o pyproject.toml seguindo as PEPs 517, 518 e 621 — os padrões oficiais do Python para metadados de projeto. Isso significa que seu projeto UV não fica preso ao UV: qualquer ferramenta compatível com essas PEPs (incluindo pip e poetry) consegue ler e usar seu pyproject.toml. Se um dia você precisar migrar, o caminho de saída está garantido.

UV e Docker

Para projetos que rodam em containers, o UV brilha especialmente na etapa de build. Um Dockerfile otimizado com UV:

FROM python:3.12-slim

# Instalar UV como binário estático (sem dependências)
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./

# Instalar dependências (camada separada para cache)
RUN uv sync --frozen --no-dev

COPY src/ ./src/

CMD ["uv", "run", "uvicorn", "meu_api.main:app", "--host", "0.0.0.0"]

O ganho em tempo de build é brutal — especialmente em pipelines de CI/CD onde cada segundo de execução tem custo real.

UV vs Cargo vs dotnet CLI

Se você vem de Rust ou .NET, vai perceber que o UV segue a mesma filosofia de CLI unificada:

Aspecto	UV (Python)	Cargo (Rust)	dotnet CLI (C#)
Criar projeto	uv init	cargo new	dotnet new
Adicionar dependência	uv add	cargo add	dotnet add package
Executar	uv run	cargo run	dotnet run
Lockfile	uv.lock	Cargo.lock	packages.lock.json
Build	— (interpretado)	cargo build	dotnet build
Testes	uv run pytest	cargo test	dotnet test

O UV é, para o Python, o que o cargo é para o Rust: a ferramenta que a comunidade esperou por décadas.

Sobre a Adoção e Comunidade

Números que mostram a tração do UV:

+40.000 estrelas no GitHub (março 2026)
Adotado pelo FastAPI como gerenciador de pacotes recomendado na documentação oficial
Integrado ao GitHub Actions como opção oficial para setup de Python
Suportado oficialmente no VS Code e PyCharm
Releases semanais com changelog detalhado e semver estrito

Quando Migrar e Quando Esperar

Se você está em um projeto com pip puro e sente a dor da lentidão e da falta de lockfile: migre agora. O custo é baixo — uv pip install -r requirements.txt funciona como drop-in replacement do pip.

Se você está com Poetry e o fluxo funciona sem dor: avalie com calma. A migração vale a pena, mas não é urgente se o projeto já está estável.

Se a empresa exige ferramentas auditadas e versionadas (1.0+): espere a versão 1.0 do UV. Mas acompanhe de perto — ela está próxima.

Conclusão

O UV é, sem exagero, o maior avanço no tooling Python dos últimos anos. Ele resolve um problema que a comunidade arrastava há mais de uma década — a fragmentação absurda de ferramentas para fazer algo que deveria ser simples: instalar pacotes, criar um ambiente e executar código.

Com o UV, você tem uma ferramenta que substitui pip, virtualenv, pyenv, pip-tools, pipx e parte do Poetry. Escrita em Rust, com velocidade absurda e aderência aos padrões PEP. Se você está começando um projeto Python novo, não há motivo para não usar UV.

Quanto ao comparativo com C#: Python é uma linguagem extraordinária para prototipagem, IA, dados e automação. Mas quando a conversa é sobre aplicações enterprise complexas com padrões arquiteturais rigorosos e manutenção a longo prazo, C# (e o .NET) oferece vantagens estruturais que são difíceis de ignorar — tipagem estática forte, DI nativa, compilação como guardião, e tooling de refactoring superior.

A maturidade de uma escolha técnica está em reconhecer: não existe linguagem perfeita para tudo. Existe a linguagem certa para o problema certo. E ter UV no arsenal torna Python significativamente mais viável para projetos sérios — porque a parte que sempre foi ruim (o gerenciamento de pacotes) finalmente ficou excelente.

Referências

UV — Documentação Oficial
Astral — Empresa por trás do UV e Ruff
Python.org — Site oficial do Python
Python Software Foundation (PSF)
PEP 20 — The Zen of Python
Ruff — Linter Python escrito em Rust
TIOBE Index
Makefile: Automatizando tarefas para Python, Hugo e Docker — artigo relacionado neste blog
Padrões GoF: Código à Nuvem, Monólito ao Microserviço — artigo relacionado neste blog 📬

👉 Artigo completo com todos os exemplos de código: pip É Lento, Poetry Complexo: UV Chegou Resolvendo o Python

Zero JavaScript: CRUD Completo com Blazor WASM e Radzen

Lincoln Zocateli — Wed, 15 Apr 2026 02:52:07 +0000

Introdução

No artigo anterior desta série, analisei se Blazor WebAssembly está pronto para produção corporativa comparando-o com Angular. A conclusão foi nuançada — Blazor WASM é viável para cenários corporativos internos, mas tem trade-offs que precisam ser avaliados caso a caso. Hoje vou provar na prática construindo um CRUD completo de produtos com DataGrid paginado, formulários com validação, dialogs, notificações e inline editing — tudo em C#, sem escrever uma linha de JavaScript.

O componente de UI que escolhi é o Radzen Blazor, uma biblioteca open source (licença MIT) com mais de 70 componentes gratuitos. A razão principal: Radzen entrega uma experiência visual madura para cenários CRUD corporativos, com DataGrid, formulários, validação, dialogs e notificações prontos para uso. O JavaScript que roda internamente (Radzen.Blazor.js) é da própria biblioteca — o desenvolvedor nunca toca em JS diretamente.

O que vou construir neste tutorial:

API REST com Minimal API para Produtos e Categorias (10 endpoints)
Blazor WASM Standalone consumindo a API via HttpClient
DataGrid paginado com busca, ordering e ações por linha
Formulário em dialog reutilizável para criação e edição
Inline editing para Categorias (pattern alternativo ao dialog)
Exclusão com confirmação e notificações visuais Todo o código está no repositório blog-zocateli-sample no GitHub. A ideia é que você clone, rode e forme sua própria opinião. Este artigo é o 2º da série “Frontend Moderno” — meu objetivo é demonstrar que o ecossistema de componentes Blazor já suporta cenários reais de produção, com uma experiência de desenvolvimento familiar para quem vem do .NET.

ℹ️ Informação: Radzen Blazor é open source (MIT) e inclui 70+ componentes free. O Radzen.Blazor.js é JavaScript interno da biblioteca — o desenvolvedor nunca escreve JavaScript diretamente. A versão usada neste tutorial é a 10.2.0 com .NET 10.

Pré-requisitos

Para acompanhar este tutorial, você vai precisar de:

.NET 10 SDK (10.0.201 ou superior) — download oficial
IDE: VS Code com extensão C# Dev Kit, ou Visual Studio 2022 17.14+
Conhecimento básico de C# e REST APIs
Terminal (PowerShell, bash ou zsh) Clone o repositório com todo o código pronto:

git clone https://github.com/lzocateli/blog-zocateli-sample.git
cd blog-zocateli-sample

Verifique se o SDK está instalado:

dotnet --version

Output esperado:

10.0.201

💡 Dica: Se você usa o VS Code com Dev Containers, o .devcontainer/ do repositório já tem o .NET 10 SDK configurado. Basta abrir o projeto no container e tudo estará pronto.

Criando o Projeto Blazor WASM Standalone

O template blazorwasm do .NET cria uma aplicação Blazor WebAssembly Standalone — uma SPA que roda inteiramente no browser via WebAssembly, sem servidor ASP.NET Core hospedando. Diferente do modelo Hosted (que inclui um projeto Server), o Standalone é uma SPA pura que consome APIs externas via HTTP, exatamente como uma aplicação Angular ou React.

Scaffolding do projeto

dotnet new blazorwasm --name BlogSamples.BlazorWasm --output frontend/blazor-wasm --framework net10.0
dotnet sln add frontend/blazor-wasm
dotnet add frontend/blazor-wasm package Radzen.Blazor

O primeiro comando cria o projeto, o segundo adiciona à solution e o terceiro instala o Radzen Blazor — a biblioteca de componentes UI. O .csproj resultante fica enxuto:

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="10.0.5" />
    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer" Version="10.0.5" PrivateAssets="all" />
    <PackageReference Include="Radzen.Blazor" Version="10.2.0" />
  </ItemGroup>
</Project>

Configurando Program.cs

O Program.cs é o entry point da SPA. Aqui configuro o HttpClient com a URL base da API (via appsettings.json), registro os services HTTP tipados e adiciono os componentes Radzen:

using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using BlogSamples.BlazorWasm;
using BlogSamples.BlazorWasm.Services;
using Radzen;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

// Configurar HttpClient com URL base da API
var apiBaseUrl = builder.Configuration["ApiBaseUrl"] ?? "http://localhost:5101";
builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(apiBaseUrl) });

// Services HTTP tipados
builder.Services.AddScoped<ProdutoApiService>();
builder.Services.AddScoped<CategoriaApiService>();

// Radzen Components (DialogService, NotificationService, etc.)
builder.Services.AddRadzenComponents();

await builder.Build().RunAsync();

A chamada AddRadzenComponents() registra automaticamente DialogService, NotificationService, TooltipService e ContextMenuService no container de DI. Sem ela, os dialogs e notificações não funcionam.

Layout com Radzen

O MainLayout.razor define a estrutura visual da aplicação — header com toggle de sidebar, navegação lateral com RadzenPanelMenu, área de conteúdo e footer:

@inherits LayoutComponentBase

<RadzenLayout>
    <RadzenHeader>
        <RadzenStack Orientation="Orientation.Horizontal" AlignItems="AlignItems.Center"
                     Gap="0.5rem" class="rz-p-2">
            <RadzenSidebarToggle Click="@(() => sidebarExpanded = !sidebarExpanded)" />
            <RadzenText Text="Blog Samples — Blazor WASM" TextStyle="TextStyle.H5"
                        class="rz-m-0" />
        </RadzenStack>
    </RadzenHeader>

    <RadzenSidebar @bind-Expanded="@sidebarExpanded">
        <RadzenPanelMenu>
            <RadzenPanelMenuItem Text="Dashboard" Icon="dashboard" Path="/" />
            <RadzenPanelMenuItem Text="Produtos" Icon="inventory_2" Path="/produtos" />
            <RadzenPanelMenuItem Text="Categorias" Icon="category" Path="/categorias" />
        </RadzenPanelMenu>
    </RadzenSidebar>

    <RadzenBody>
        <div class="rz-p-4">
            @Body
        </div>
    </RadzenBody>

    <RadzenFooter>
        <RadzenText Text="© 2026 Blog Samples — zocate.li" TextStyle="TextStyle.Caption"
                    class="rz-p-2" />
    </RadzenFooter>
</RadzenLayout>

<RadzenComponents />

@code {
    bool sidebarExpanded = true;
}

O componente <RadzenComponents /> no final é obrigatório — ele renderiza os containers para dialogs, notificações e tooltips. Sem ele, DialogService.OpenAsync() e NotificationService.Notify() não exibem nada na tela.

⚠️ Atenção: O <RadzenComponents /> deve estar dentro do layout, não no App.razor. Colocá-lo fora do layout pode causar problemas de renderização com dialogs e notificações.

Para que o tema visual funcione, o App.razor precisa incluir <RadzenTheme Theme="material" />:

<RadzenTheme Theme="material" />
<Router AppAssembly="typeof(Program).Assembly">
    <!-- ... -->
</Router>

O tema material do Radzen inclui toda a estilização necessária — cores, tipografia, espaçamento, ícones Material Design. Não é necessário importar Bootstrap ou qualquer outro framework CSS.

A API REST — Domínio Produtos

Para o Blazor WASM consumir dados, criei um domínio Produtos com Minimal API no projeto principal. São 10 endpoints organizados em dois grupos:

Verbo	Rota	Descrição
GET	/api/produtos?pagina=1&tamanhoPagina=20&filtro=	Listar com paginação e filtro
GET	/api/produtos/{id}	Obter por ID
POST	/api/produtos	Criar produto
PUT	/api/produtos/{id}	Atualizar produto
DELETE	/api/produtos/{id}	Remover produto
GET	/api/categorias	Listar todas
GET	/api/categorias/{id}	Obter por ID
POST	/api/categorias	Criar categoria
PUT	/api/categorias/{id}	Atualizar categoria
DELETE	/api/categorias/{id}	Remover categoria

O ProdutoEndpoints.cs usa MapGroup para organizar as rotas e ProducesResponseType para documentar no Swagger:

public static class ProdutoEndpoints
{
    public static void MapProdutoEndpoints(this IEndpointRouteBuilder app)
    {
        var produtos = app.MapGroup("/api/produtos")
            .WithTags("Produtos");

        produtos.MapGet("/", async (
            IProdutoService service,
            int pagina = 1,
            int tamanhoPagina = 20,
            string? filtro = null) =>
        {
            var resultado = await service.ListarProdutosAsync(pagina, tamanhoPagina, filtro);
            return Results.Ok(resultado);
        })
        .WithName("ListarProdutos")
        .Produces<PagedResult<ProdutoDto>>();

        produtos.MapPost("/", async (CriarProdutoRequest request, IProdutoService service) =>
        {
            var produto = await service.CriarProdutoAsync(request);
            return Results.CreatedAtRoute("ObterProduto", new { id = produto.Id }, produto);
        })
        .WithName("CriarProduto")
        .Produces<ProdutoDto>(201)
        .ProducesValidationProblem();

        // ... PUT, DELETE, e endpoints de Categorias seguem o mesmo pattern
    }
}

Os DTOs de request usam DataAnnotations para validação server-side, garantindo que a API valide os dados mesmo que o client-side seja bypassed:

public record CriarProdutoRequest
{
    [Required(ErrorMessage = "Nome é obrigatório")]
    [StringLength(200, MinimumLength = 3)]
    public string Nome { get; init; } = string.Empty;

    public string? Descricao { get; init; }

    [Range(0.01, double.MaxValue, ErrorMessage = "Preço deve ser maior que zero")]
    public decimal Preco { get; init; }

    [Range(0, int.MaxValue)]
    public int QuantidadeEstoque { get; init; }

    [Range(1, int.MaxValue, ErrorMessage = "Selecione uma categoria")]
    public int CategoriaId { get; init; }

    public bool Ativo { get; init; } = true;
}

A implementação do service usa ConcurrentDictionary como storage in-memory (decisão de design para manter o tutorial focado no Blazor WASM, sem dependência de banco de dados). O seed inicial inclui 8 categorias e mais de 50 produtos distribuídos entre elas.

Configuração CORS

Como o Blazor WASM Standalone roda em uma porta diferente da API (5200 vs 5101), é obrigatório configurar CORS no Program.cs da API:

builder.Services.AddCors(options =>
{
    options.AddPolicy("BlazorWasm", policy =>
    {
        policy.WithOrigins("http://localhost:5200", "https://localhost:7200")
              .AllowAnyHeader()
              .AllowAnyMethod();
    });
});

// No pipeline:
app.UseCors("BlazorWasm");

💡 Dica: Configurar CORS é obrigatório para Blazor WASM Standalone. Sem configuração explícita, o browser bloqueará as requisições cross-origin. Em produção, substitua os origins por domínios reais.

Para testar a API isoladamente, rode dotnet run --project src/BlogSamples e acesse http://localhost:5101/docs — o Swagger mostra todos os endpoints de Produtos e Categorias.

O diagrama abaixo mostra a arquitetura completa — o Blazor WASM no browser se comunica com a API REST via HttpClient (JSON) atravessando a barreira de CORS:

Services HTTP — Consumindo a API

O pattern que uso para consumir a API é service tipado com HttpClient injetado via primary constructor. Cada service encapsula as chamadas HTTP para um domínio específico, usando os métodos de extensão do System.Net.Http.Json — GetFromJsonAsync, PostAsJsonAsync e PutAsJsonAsync:

using System.Net.Http.Json;
using BlogSamples.BlazorWasm.Models;

namespace BlogSamples.BlazorWasm.Services;

public class ProdutoApiService(HttpClient http)
{
    public async Task<PagedResult<ProdutoDto>> ListarAsync(
        int pagina = 1, int tamanhoPagina = 20, string? filtro = null)
    {
        var url = $"api/produtos?pagina={pagina}&tamanhoPagina={tamanhoPagina}";
        if (!string.IsNullOrWhiteSpace(filtro))
            url += $"&filtro={Uri.EscapeDataString(filtro)}";

        return await http.GetFromJsonAsync<PagedResult<ProdutoDto>>(url)
            ?? new PagedResult<ProdutoDto>();
    }

    public async Task<ProdutoDto?> ObterPorIdAsync(int id)
        => await http.GetFromJsonAsync<ProdutoDto>($"api/produtos/{id}");

    public async Task<ProdutoDto?> CriarAsync(CriarProdutoRequest request)
    {
        var response = await http.PostAsJsonAsync("api/produtos", request);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<ProdutoDto>();
    }

    public async Task<ProdutoDto?> AtualizarAsync(int id, AtualizarProdutoRequest request)
    {
        var response = await http.PutAsJsonAsync($"api/produtos/{id}", request);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<ProdutoDto>();
    }

    public async Task RemoverAsync(int id)
    {
        var response = await http.DeleteAsync($"api/produtos/{id}");
        response.EnsureSuccessStatusCode();
    }
}

Alguns pontos importantes sobre este pattern:

Uri.EscapeDataString no filtro previne injeção de parâmetros na query string. Nunca concatene strings diretamente em URLs sem encoding.
EnsureSuccessStatusCode() lança HttpRequestException se a API retornar erro (4xx, 5xx). No componente Blazor, capturo essa exceção para exibir notificação de erro ao usuário.
Primary constructor (HttpClient http) evita o boilerplate de campo + construtor. O HttpClient é resolvido pelo container de DI com a BaseAddress configurada no Program.cs. O CategoriaApiService segue exatamente o mesmo pattern, com métodos ListarAsync, CriarAsync, AtualizarAsync e RemoverAsync.

No Angular, HttpClient com interceptors e operadores RxJS oferece ergonomia similar. Em Blazor, a experiência é equivalente — DelegatingHandler serve como interceptor para autenticação, logging ou retry. A diferença principal é que Blazor usa async/await nativo do C# em vez de Observable do RxJS.

ℹ️ Informação: Os models do Blazor WASM são classes (não records). Radzen Blazor usa two-way binding (@bind-Value) que requer setters mutáveis. Records com init não funcionam para edição em formulários Radzen.

DataGrid de Produtos com Radzen

O RadzenDataGrid é o componente central deste tutorial. Ele suporta paginação server-side, sorting, filtering, templates customizados por coluna e integração direta com o pattern de LoadData — um callback que o grid chama toda vez que precisa de dados novos (ao mudar de página, ordenar ou filtrar).

Aqui está o Produtos.razor completo — vou explicar cada parte:

@page "/produtos"

<PageTitle>Produtos — Blog Samples</PageTitle>

<RadzenText TextStyle="TextStyle.H3" class="rz-mb-4">Produtos</RadzenText>

<RadzenStack Orientation="Orientation.Horizontal" AlignItems="AlignItems.Center"
             Gap="1rem" class="rz-mb-4">
    <RadzenTextBox Placeholder="Buscar produtos..." @bind-Value="filtro"
                   Change="@OnFiltroChanged" Style="width: 300px;" />
    <RadzenButton Text="Novo Produto" Icon="add" ButtonStyle="ButtonStyle.Primary"
                  Click="@(() => AbrirFormulario(null))" />
</RadzenStack>

<RadzenDataGrid @ref="grid" TItem="ProdutoDto"
                Data="@produtos" Count="@totalRegistros"
                LoadData="@CarregarDados"
                AllowPaging="true" PageSize="20"
                AllowSorting="true"
                PagerHorizontalAlign="HorizontalAlign.Center"
                IsLoading="@isLoading"
                Style="width: 100%;">
    <Columns>
        <RadzenDataGridColumn TItem="ProdutoDto" Property="Id" Title="ID"
                              Width="70px" TextAlign="TextAlign.Center" Sortable="false" />

        <RadzenDataGridColumn TItem="ProdutoDto" Property="Nome" Title="Nome"
                              MinWidth="200px" />

        <RadzenDataGridColumn TItem="ProdutoDto" Property="CategoriaNome" Title="Categoria"
                              Width="150px" />

        <RadzenDataGridColumn TItem="ProdutoDto" Property="Preco" Title="Preço"
                              Width="130px" TextAlign="TextAlign.End"
                              FormatString="{0:C2}" />

        <RadzenDataGridColumn TItem="ProdutoDto" Property="QuantidadeEstoque" Title="Estoque"
                              Width="100px" TextAlign="TextAlign.Center" />

        <RadzenDataGridColumn TItem="ProdutoDto" Property="Ativo" Title="Status"
                              Width="100px" TextAlign="TextAlign.Center" Sortable="false">
            <Template Context="produto">
                <RadzenBadge BadgeStyle="@(produto.Ativo ? BadgeStyle.Success : BadgeStyle.Light)"
                             Text="@(produto.Ativo ? "Ativo" : "Inativo")" />
            </Template>
        </RadzenDataGridColumn>

        <RadzenDataGridColumn TItem="ProdutoDto" Title="Ações" Width="140px"
                              TextAlign="TextAlign.Center" Sortable="false">
            <Template Context="produto">
                <RadzenButton Icon="edit" ButtonStyle="ButtonStyle.Light"
                              Size="ButtonSize.Small"
                              Click="@(() => AbrirFormulario(produto.Id))"
                              class="rz-mr-1" />
                <RadzenButton Icon="delete" ButtonStyle="ButtonStyle.Danger"
                              Size="ButtonSize.Small"
                              Click="@(() => ConfirmarExclusao(produto))" />
            </Template>
        </RadzenDataGridColumn>
    </Columns>
</RadzenDataGrid>

Vou detalhar os pontos-chave:

LoadData="@CarregarDados" — o grid chama este callback ao inicializar, ao mudar de página e ao ordenar. Recebe LoadDataArgs com Skip, Top e informações de ordering. Essa é a chave para paginação server-side.
Data + Count — Data recebe a página atual de itens; Count informa o total de registros. O grid calcula o número de páginas automaticamente.
FormatString="{0:C2}" — formata o preço como moeda. O Blazor WASM usa a cultura configurada no browser, então em pt-BR exibe “R$ 1.299,00”.
Template — colunas customizadas. Uso RadzenBadge para exibir o status como badge verde/cinza e botões de ação (Editar, Excluir) com ícones Material Design.
IsLoading — exibe um spinner enquanto a API está sendo chamada. Melhora significativamente a UX em conexões lentas. O @code block contém a lógica:

@code {
    RadzenDataGrid<ProdutoDto> grid = default!;
    IEnumerable<ProdutoDto> produtos = [];
    int totalRegistros;
    string? filtro;
    bool isLoading;

    [Inject] ProdutoApiService ProdutoService { get; set; } = default!;
    [Inject] DialogService DialogService { get; set; } = default!;
    [Inject] NotificationService NotificationService { get; set; } = default!;

    async Task CarregarDados(LoadDataArgs args)
    {
        isLoading = true;

        var pagina = (args.Skip ?? 0) / (args.Top ?? 20) + 1;
        var tamanhoPagina = args.Top ?? 20;

        var resultado = await ProdutoService.ListarAsync(pagina, tamanhoPagina, filtro);

        produtos = resultado.Itens;
        totalRegistros = resultado.TotalRegistros;

        isLoading = false;
    }

    async Task OnFiltroChanged()
    {
        await grid.FirstPage(true);
    }
}

O método CarregarDados converte Skip/Top (pattern do Radzen) para pagina/tamanhoPagina (pattern da minha API). Quando o usuário digita no campo de busca, OnFiltroChanged volta para a primeira página com grid.FirstPage(true) — o true força o reload que chama CarregarDados novamente com o filtro atualizado.

⚠️ Atenção: O evento LoadData do RadzenDataGrid é chamado toda vez que o grid precisa de dados — paging, sorting, filtering. Não confunda com Data binding direto, que é para dados client-side. Se você usar Data com uma lista completa e AllowPaging, a paginação será client-side (todos os dados carregados de uma vez). Com LoadData + Count, a paginação é server-side (apenas a página atual é carregada).

Formulário de Criação e Edição

O ProdutoForm.razor é um componente reutilizável que serve tanto para criar quanto para editar produtos. A distinção é feita pelo Parameter ProdutoId: se for null, é criação; se tiver valor, é edição. O formulário é aberto em um dialog modal via DialogService.OpenAsync<ProdutoForm>().

<RadzenTemplateForm TItem="CriarProdutoRequest" Data="@model" Submit="@OnSubmit">
    <RadzenStack Gap="1rem">
        <RadzenFormField Text="Nome" Variant="Variant.Outlined">
            <ChildContent>
                <RadzenTextBox @bind-Value="model.Nome" MaxLength="200" />
            </ChildContent>
            <Helper>
                <RadzenRequiredValidator Component="Nome"
                                         Text="Nome é obrigatório" />
            </Helper>
        </RadzenFormField>

        <RadzenFormField Text="Descrição" Variant="Variant.Outlined">
            <ChildContent>
                <RadzenTextArea @bind-Value="model.Descricao" Rows="3" />
            </ChildContent>
        </RadzenFormField>

        <RadzenRow Gap="1rem">
            <RadzenColumn Size="6">
                <RadzenFormField Text="Preço (R$)" Variant="Variant.Outlined"
                                Style="width: 100%;">
                    <ChildContent>
                        <RadzenNumeric TValue="decimal" @bind-Value="model.Preco"
                                       Min="0.01m" Format="N2" />
                    </ChildContent>
                    <Helper>
                        <RadzenNumericRangeValidator Component="Preco" Min="0.01"
                                                     Text="Preço deve ser maior que zero" />
                    </Helper>
                </RadzenFormField>
            </RadzenColumn>
            <RadzenColumn Size="6">
                <RadzenFormField Text="Estoque" Variant="Variant.Outlined"
                                Style="width: 100%;">
                    <ChildContent>
                        <RadzenNumeric TValue="int" @bind-Value="model.QuantidadeEstoque"
                                       Min="0" />
                    </ChildContent>
                </RadzenFormField>
            </RadzenColumn>
        </RadzenRow>

        <RadzenFormField Text="Categoria" Variant="Variant.Outlined">
            <ChildContent>
                <RadzenDropDown TValue="int" @bind-Value="model.CategoriaId"
                                Data="@categorias" TextProperty="Nome"
                                ValueProperty="Id"
                                Placeholder="Selecione uma categoria..."
                                AllowFiltering="true" />
            </ChildContent>
            <Helper>
                <RadzenRequiredValidator Component="CategoriaId"
                                         Text="Selecione uma categoria"
                                         DefaultValue="0" />
            </Helper>
        </RadzenFormField>

        <RadzenStack Orientation="Orientation.Horizontal" AlignItems="AlignItems.Center"
                     Gap="0.5rem">
            <RadzenSwitch @bind-Value="model.Ativo" />
            <RadzenText Text="@(model.Ativo ? "Ativo" : "Inativo")" />
        </RadzenStack>

        <RadzenStack Orientation="Orientation.Horizontal"
                     JustifyContent="JustifyContent.End" Gap="0.5rem">
            <RadzenButton Text="Cancelar" ButtonStyle="ButtonStyle.Light"
                          Click="@(() => DialogService.Close(false))"
                          ButtonType="ButtonType.Button" />
            <RadzenButton Text="Salvar" ButtonStyle="ButtonStyle.Primary"
                          ButtonType="ButtonType.Submit" Icon="save" />
        </RadzenStack>
    </RadzenStack>
</RadzenTemplateForm>

Vou destacar os pontos mais importantes do formulário:

RadzenTemplateForm<CriarProdutoRequest> — encapsula todo o formulário com validação. O Submit event só é disparado se todos os validators passarem.
RadzenRequiredValidator e RadzenNumericRangeValidator — validação client-side com feedback visual automático (bordas vermelhas, mensagem de erro abaixo do campo). A validação server-side via DataAnnotations na API é a segunda camada de proteção.
RadzenDropDown<int> para categorias — Data recebe a lista, TextProperty e ValueProperty mapeiam as propriedades do DTO. AllowFiltering="true" habilita busca inline no dropdown (útil quando há muitas categorias).
RadzenSwitch com label dinâmico — exibe “Ativo” ou “Inativo” conforme o estado do toggle.
Botão Cancelar com ButtonType="ButtonType.Button" — sem isso, o click do Cancelar dispara o submit do formulário. O @code block contém a lógica de inicialização e submit:

@code {
    [Parameter] public int? ProdutoId { get; set; }

    [Inject] ProdutoApiService ProdutoService { get; set; } = default!;
    [Inject] CategoriaApiService CategoriaService { get; set; } = default!;
    [Inject] DialogService DialogService { get; set; } = default!;
    [Inject] NotificationService NotificationService { get; set; } = default!;

    CriarProdutoRequest model = new();
    IReadOnlyList<CategoriaDto> categorias = [];

    protected override async Task OnInitializedAsync()
    {
        categorias = await CategoriaService.ListarAsync();

        if (ProdutoId.HasValue)
        {
            var produto = await ProdutoService.ObterPorIdAsync(ProdutoId.Value);
            if (produto is not null)
            {
                model = new CriarProdutoRequest
                {
                    Nome = produto.Nome,
                    Descricao = produto.Descricao,
                    Preco = produto.Preco,
                    QuantidadeEstoque = produto.QuantidadeEstoque,
                    CategoriaId = produto.CategoriaId,
                    Ativo = produto.Ativo
                };
            }
        }
    }

    async Task OnSubmit()
    {
        try
        {
            if (ProdutoId.HasValue)
            {
                var request = new AtualizarProdutoRequest
                {
                    Nome = model.Nome,
                    Descricao = model.Descricao,
                    Preco = model.Preco,
                    QuantidadeEstoque = model.QuantidadeEstoque,
                    CategoriaId = model.CategoriaId,
                    Ativo = model.Ativo
                };
                await ProdutoService.AtualizarAsync(ProdutoId.Value, request);
            }
            else
            {
                await ProdutoService.CriarAsync(model);
            }

            DialogService.Close(true);
        }
        catch (HttpRequestException)
        {
            NotificationService.Notify(new NotificationMessage
            {
                Severity = NotificationSeverity.Error,
                Summary = "Erro ao salvar",
                Detail = "Não foi possível salvar o produto.",
                Duration = 6000
            });
        }
    }
}

O fluxo completo é: usuário clica “Novo Produto” → DialogService.OpenAsync<ProdutoForm>() abre o dialog → o form carrega categorias e, se for edição, carrega o produto → usuário preenche/edita → validators verificam → OnSubmit chama a API → DialogService.Close(true) fecha o dialog → o grid detecta resultado is true e chama grid.Reload() → dados atualizados.

Para abrir o dialog a partir de Produtos.razor:

async Task AbrirFormulario(int? produtoId)
{
    var titulo = produtoId.HasValue ? "Editar Produto" : "Novo Produto";

    var resultado = await DialogService.OpenAsync<ProdutoForm>(titulo,
        new Dictionary<string, object?> { { "ProdutoId", produtoId } },
        new DialogOptions
        {
            Width = "600px",
            CloseDialogOnOverlayClick = false,
            CloseDialogOnEsc = true
        });

    if (resultado is true)
    {
        await grid.Reload();
    }
}

O dicionário { "ProdutoId", produtoId } passa o parâmetro para o componente ProdutoForm. O DialogOptions controla a largura do dialog e se ele fecha ao clicar fora ou pressionar Escape.

📝 Exemplo: Fluxo de edição — clique no botão “Editar” de um produto → dialog abre com título “Editar Produto” → campos preenchidos com dados atuais → altere o preço → clique Salvar → notificação verde “Produto atualizado” → grid recarrega com preço novo.

Exclusão com Confirmação e Notificações

Toda operação destrutiva deve ter uma etapa de confirmação. O DialogService.Confirm() do Radzen renderiza um dialog nativo com botões customizáveis:

async Task ConfirmarExclusao(ProdutoDto produto)
{
    var confirmado = await DialogService.Confirm(
        $"Deseja excluir o produto \"{produto.Nome}\"?",
        "Confirmar Exclusão",
        new ConfirmOptions
        {
            OkButtonText = "Excluir",
            CancelButtonText = "Cancelar"
        });

    if (confirmado == true)
    {
        try
        {
            await ProdutoService.RemoverAsync(produto.Id);
            NotificationService.Notify(new NotificationMessage
            {
                Severity = NotificationSeverity.Success,
                Summary = "Produto excluído",
                Detail = $"\"{produto.Nome}\" foi removido com sucesso.",
                Duration = 4000
            });
            await grid.Reload();
        }
        catch (HttpRequestException)
        {
            NotificationService.Notify(new NotificationMessage
            {
                Severity = NotificationSeverity.Error,
                Summary = "Erro ao excluir",
                Detail = "Não foi possível excluir o produto. Tente novamente.",
                Duration = 6000
            });
        }
    }
}

As notificações do Radzen (NotificationService.Notify) aparecem como toasts no canto da tela. Uso NotificationSeverity.Success com duração de 4 segundos para operações bem-sucedidas e NotificationSeverity.Error com 6 segundos para erros — mais tempo para o usuário ler a mensagem. O pattern de try/catch com HttpRequestException é simples mas eficaz: se a API retornar erro (ex: produto não encontrado), o catch exibe feedback imediato ao usuário.

Gerenciamento de Categorias — Inline Editing

Para demonstrar um pattern alternativo ao dialog, a tela de Categorias usa inline editing — o usuário edita diretamente na grid, sem abrir modal. Esse approach funciona bem para entidades simples com poucos campos.

@page "/categorias"

<RadzenDataGrid @ref="grid" TItem="CategoriaDto"
                Data="@categorias" AllowSorting="true"
                EditMode="DataGridEditMode.Single"
                RowUpdate="@OnRowUpdate" RowCreate="@OnRowCreate"
                Style="width: 100%;">
    <Columns>
        <RadzenDataGridColumn TItem="CategoriaDto" Property="Id" Title="ID"
                              Width="70px" TextAlign="TextAlign.Center" />

        <RadzenDataGridColumn TItem="CategoriaDto" Property="Nome" Title="Nome"
                              MinWidth="200px">
            <EditTemplate Context="cat">
                <RadzenTextBox @bind-Value="cat.Nome" Style="width: 100%;" />
            </EditTemplate>
        </RadzenDataGridColumn>

        <RadzenDataGridColumn TItem="CategoriaDto" Property="Descricao"
                              Title="Descrição" MinWidth="250px">
            <EditTemplate Context="cat">
                <RadzenTextBox @bind-Value="cat.Descricao" Style="width: 100%;" />
            </EditTemplate>
        </RadzenDataGridColumn>

        <RadzenDataGridColumn TItem="CategoriaDto" Property="Ativo" Title="Status"
                              Width="100px" TextAlign="TextAlign.Center">
            <Template Context="cat">
                <RadzenBadge BadgeStyle="@(cat.Ativo ? BadgeStyle.Success : BadgeStyle.Light)"
                             Text="@(cat.Ativo ? "Ativo" : "Inativo")" />
            </Template>
            <EditTemplate Context="cat">
                <RadzenSwitch @bind-Value="cat.Ativo" />
            </EditTemplate>
        </RadzenDataGridColumn>

        <RadzenDataGridColumn TItem="CategoriaDto" Title="Ações" Width="180px"
                              TextAlign="TextAlign.Center" Sortable="false">
            <Template Context="cat">
                <RadzenButton Icon="edit" ButtonStyle="ButtonStyle.Light"
                              Size="ButtonSize.Small"
                              Click="@(() => EditarLinha(cat))" class="rz-mr-1" />
                <RadzenButton Icon="delete" ButtonStyle="ButtonStyle.Danger"
                              Size="ButtonSize.Small"
                              Click="@(() => ConfirmarExclusao(cat))" />
            </Template>
            <EditTemplate Context="cat">
                <RadzenButton Icon="check" ButtonStyle="ButtonStyle.Success"
                              Size="ButtonSize.Small"
                              Click="@(() => SalvarLinha(cat))" class="rz-mr-1" />
                <RadzenButton Icon="close" ButtonStyle="ButtonStyle.Light"
                              Size="ButtonSize.Small"
                              Click="@CancelarEdicao" />
            </EditTemplate>
        </RadzenDataGridColumn>
    </Columns>
</RadzenDataGrid>

A diferença principal está no EditMode="DataGridEditMode.Single": quando o usuário clica em “Editar”, a linha entra em modo de edição — os campos de texto e o switch aparecem no lugar dos valores estáticos. Os botões mudam de “Editar/Excluir” para “Salvar/Cancelar”.

A lógica de edição inline:

@code {
    RadzenDataGrid<CategoriaDto> grid = default!;
    IList<CategoriaDto> categorias = [];
    CategoriaDto? categoriaEditando;

    async Task InserirNova()
    {
        var nova = new CategoriaDto { Ativo = true };
        categorias.Insert(0, nova);
        categoriaEditando = nova;
        await grid.EditRow(nova);
    }

    async Task EditarLinha(CategoriaDto cat)
    {
        categoriaEditando = cat;
        await grid.EditRow(cat);
    }

    async Task SalvarLinha(CategoriaDto cat)
    {
        await grid.UpdateRow(cat);
    }

    async Task OnRowUpdate(CategoriaDto cat)
    {
        var request = new AtualizarCategoriaRequest
        {
            Nome = cat.Nome,
            Descricao = cat.Descricao,
            Ativo = cat.Ativo
        };
        await CategoriaService.AtualizarAsync(cat.Id, request);
        categoriaEditando = null;
        await CarregarDados();
    }

    async Task OnRowCreate(CategoriaDto cat)
    {
        var request = new CriarCategoriaRequest
        {
            Nome = cat.Nome,
            Descricao = cat.Descricao,
            Ativo = cat.Ativo
        };
        await CategoriaService.CriarAsync(request);
        categoriaEditando = null;
        await CarregarDados();
    }
}

O fluxo para “Nova Categoria” é: inserir um objeto vazio na posição 0 da lista → grid.EditRow() coloca essa linha em modo de edição → usuário preenche → SalvarLinha chama grid.UpdateRow() → OnRowCreate é disparado (porque Id == 0) → API chamada → dados recarregados.

Quando usar inline editing vs dialog:

Cenário	Inline Editing	Dialog
Entidades simples (2-4 campos)	✅ Ideal	Overkill
Entidades complexas (5+ campos, dropdowns)	Confuso	✅ Ideal
Campos com validação elaborada	Limitado	✅ Mais espaço visual
Edição rápida e frequente	✅ Menos cliques	Mais cliques
UX mobile	⚠️ Pode ficar apertado	✅ Melhor em telas pequenas

Dicas e Boas Práticas

Centralize chamadas HTTP em services tipados — nunca injete HttpClient diretamente no componente .razor. Isso viola separação de responsabilidades e dificulta testes. Services como ProdutoApiService encapsulam URLs, serialização e tratamento de erros em um único lugar reutilizável.
Use DataAnnotations + validators Radzen para validação dupla — RadzenRequiredValidator e RadzenNumericRangeValidator validam no client; DataAnnotations no DTO de request validam no server. Se alguém bypassar o UI e chamar a API diretamente, a validação server-side ainda protege os dados.
RadzenNotification para TODA ação — feedback visual consistente em sucesso (“Produto criado”) e erro (“Não foi possível salvar”). Defina duração diferente: 4 segundos para sucesso, 6+ para erros (o usuário precisa de mais tempo para ler a mensagem de erro).
LoadData event para paginação server-side — nunca carregue todos os dados no client com uma lista completa. Com LoadData, apenas a página atual é transferida pela rede. Para um catálogo com 10.000 produtos, carregar tudo na memória do browser é inviável; com paginação server-side, cada request traz apenas 20 registros.
Componentize forms reutilizáveis — ProdutoForm serve para criação E edição. A distinção é um Parameter nullable (int? ProdutoId). Esse pattern elimina duplicação de código e garante consistência entre os fluxos de criação e edição.
Configure appsettings.json para URL da API — nunca faça hardcode de URLs. O wwwroot/appsettings.json no Blazor WASM funciona como arquivo de configuração por ambiente. Em produção, substitua por appsettings.Production.json com a URL real da API.
Implemente loading state no DataGrid — a propriedade IsLoading do RadzenDataGrid exibe um spinner enquanto a API é chamada. Sem feedback visual, o usuário não sabe se a ação foi disparada ou se a aplicação travou. Defina isLoading = true antes da chamada e false depois.
Configure AOT + Trimming para produção — o bundle size do Blazor WASM é uma preocupação real. Para produção, habilite AOT compilation e trimming no .csproj:

<PropertyGroup>
  <RunAOTCompilation>true</RunAOTCompilation>
  <PublishTrimmed>true</PublishTrimmed>
</PropertyGroup>

AOT compila o IL para WebAssembly nativo (execução mais rápida), e trimming remove código não utilizado (bundle menor). O trade-off é tempo de build significativamente maior.

Conclusão

Neste tutorial, construí um CRUD completo com Blazor WebAssembly .NET 10 e Radzen Blazor: DataGrid com paginação server-side e busca, formulários com validação client-side e server-side, dialogs modais para criação e edição, inline editing para entidades simples, exclusão com confirmação e notificações visuais para feedback — tudo em C#, sem escrever uma linha de JavaScript pelo desenvolvedor.

Radzen Blazor entrega componentes visuais maduros para o cenário CRUD corporativo. O RadzenDataGrid com LoadData resolve paginação server-side de forma elegante. Os validators (RadzenRequiredValidator, RadzenNumericRangeValidator) funcionam bem para validação básica. O DialogService e NotificationService cobrem o fluxo completo de interação com o usuário.

Mas é importante ser transparente sobre as limitações que encontrei durante o desenvolvimento:

Radzen.Blazor.js é necessário — apesar do slogan “zero JavaScript”, a biblioteca depende de JS interno para renderizar componentes complexos. Não é JavaScript escrito pelo desenvolvedor, mas é JS rodando no browser.
Two-way binding requer classes, não records — @bind-Value do Radzen precisa de setters mutáveis. Records com init não funcionam para formulários de edição. Isso força o uso de classes para DTOs no Blazor WASM.
O bundle size continua significativo — o runtime do .NET + Radzen + a aplicação resultam em um download inicial considerável. AOT e trimming ajudam, mas não resolvem completamente. Como analisei no artigo anterior, Blazor WASM é viável para contextos corporativos — e este tutorial demonstra que o ecossistema de componentes suporta cenários reais. A decisão entre Blazor WASM e frameworks JavaScript como Angular ou React depende do perfil da equipe, requisitos de SEO/SSR e tolerância ao bundle size, conforme discuti no comparativo.

Clone o repositório, rode a API e o Blazor WASM, e forme sua própria opinião. O código completo está em frontend/blazor-wasm/ e src/BlogSamples/Produtos/.

Referências

Blazor WebAssembly — Documentação oficial — Microsoft Learn, referência completa sobre Blazor
ASP.NET Core 10.0 Release Notes — novidades do .NET 10 para web
Radzen Blazor Components — Get Started — setup e guia inicial da biblioteca
Radzen Blazor — GitHub — código fonte (MIT) com exemplos e issues
Radzen DataGrid — documentação e demos interativos do componente central
blog-zocateli-sample — GitHub — repositório com todo o código deste artigo
WebAssembly — especificação oficial do padrão W3C
Blazor WASM Standalone Deployment — guia de deploy para produção 📬

👉 Artigo completo com todos os exemplos de código: Zero JavaScript: CRUD Completo com Blazor WASM e Radzen

Paginação em APIs REST com C# e EF Core: Guia Prático

Lincoln Zocateli — Wed, 15 Apr 2026 02:45:56 +0000

Introdução

Paginar resultados parece simples: adicione .Skip(offset).Take(pageSize) e pronto. Mas quando a tabela tem 10 milhões de registros, o usuário está na página 5.000, o banco é Oracle 11g, ou o cliente exige scroll infinito sem duplicatas — essa simplicidade desaparece rapidamente.

Paginação é uma das decisões arquiteturais mais impactantes em APIs REST, e a escolha errada pode significar queries de 8 segundos, resultados inconsistentes ou um backend que trava sob carga. Existem pelo menos cinco estratégias distintas, cada uma com trade-offs claros: Offset, Keyset (Seek), Cursor de banco, Token opaco e Time-based. Cada banco de dados — SQL Server, Oracle e PostgreSQL — implementa essas estratégias com sintaxes e comportamentos ligeiramente diferentes.

Neste artigo você vai entender em profundidade quando usar cada estratégia, como cada banco a implementa, e como codificar tudo com EF Core 8.0+ em C#. Se você quer uma visão mais ampla sobre gargalos de leitura e escrita em banco de dados, leia também o artigo Gargalo em Banco de Dados com C# e EF Core: Mensageria e Paginação.

Pré-requisitos: C# intermediário, EF Core básico, familiaridade com SQL. Recomenda-se também o artigo sobre programação assíncrona com C#.

📦 Código-fonte: A implementação completa deste artigo está no repositório blog-zocateli-sample no GitHub. Clone, explore e adapte ao seu contexto.

Por Que Paginação Errada Destrói a Performance

Antes de ver as estratégias, vale entender o que acontece internamente em cada banco quando você pagina:

O Problema do OFFSET Profundo

-- SQL Server: página 5000 com 20 itens por página
SELECT Id, Nome, Valor FROM Pedidos
ORDER BY DataCriacao
OFFSET 99980 ROWS FETCH NEXT 20 ROWS ONLY;

O banco não “pula” para a linha 99.981 magicamente. Ele precisa:

Ordenar (ou usar o índice de ordenação)
Varrer 99.980 linhas e descartá-las
Retornar as próximas 20 O custo cresce linearmente com o offset. Para OFFSET 0 o custo é quase zero; para OFFSET 1.000.000 o custo pode ser segundos. Isso é o problema do late pagination, e se manifesta em qualquer banco.

Por Que Ordering Estável é Mandatório

// ❌ SEM OrderBy — resultado não determinístico
var dados = await context.Pedidos.Skip(40).Take(20).ToListAsync();

// ✅ COM OrderBy — resultado determinístico + índice pode ser usado
var dados = await context.Pedidos
    .OrderBy(p => p.DataCriacao)
    .ThenBy(p => p.Id)        // Desempate pelo campo único garante estabilidade
    .Skip(40).Take(20)
    .ToListAsync();

Sem OrderBy, o banco pode retornar os 20 itens em qualquer ordem, e você corre o risco de ver os mesmos registros em páginas diferentes ou pular registros. Isso é especialmente crítico no Oracle, que tem comportamento de ordenação menos previsível que o SQL Server por padrão.

Estratégia 1: Offset Pagination (SKIP / TAKE)

Quando Usar

UIs com número de páginas visível (página 1, 2, 3&mldr;)
Relatórios com totais exatos necessários
Volumes pequenos ou médios (até ~100k registros na tabela)
Quando o usuário precisa saltar diretamente para qualquer página

O SQL por Banco

-- SQL Server (2012+)
SELECT Id, ClienteId, Valor, DataCriacao
FROM Pedidos
ORDER BY DataCriacao, Id
OFFSET 40 ROWS FETCH NEXT 20 ROWS ONLY;

-- Oracle 12c+
SELECT Id, ClienteId, Valor, DataCriacao
FROM Pedidos
ORDER BY DataCriacao, Id
OFFSET 40 ROWS FETCH NEXT 20 ROWS ONLY;

-- Oracle 11g (sem suporte nativo — ROW_NUMBER workaround)
SELECT * FROM (
    SELECT p.*, ROWNUM AS rn
    FROM (
        SELECT Id, ClienteId, Valor, DataCriacao
        FROM Pedidos
        ORDER BY DataCriacao, Id
    ) p
    WHERE ROWNUM <= 60
)
WHERE rn > 40;

-- PostgreSQL
SELECT Id, ClienteId, Valor, DataCriacao
FROM Pedidos
ORDER BY DataCriacao, Id
LIMIT 20 OFFSET 40;

💡 Dica: O provider Oracle.EntityFrameworkCore detecta automaticamente a versão do Oracle e gera a sintaxe correta (com FETCH FIRST para 12c+ ou ROWNUM para 11g). Não precisa escrever SQL raw para isso.

Implementação com EF Core 8

// Models reutilizáveis para toda a API
public record PaginacaoRequest(
    int Pagina      = 1,
    int TamanhoPagina = 20)
{
    public int TamanhoSeguro => Math.Clamp(TamanhoPagina, 1, 100);
    public int OffsetSeguro  => (Math.Max(Pagina, 1) - 1) * TamanhoSeguro;
}

public record PaginaResultado<T>(
    IReadOnlyList<T>  Dados,
    int               PaginaAtual,
    int               TamanhoPagina,
    long              TotalRegistros,
    int               TotalPaginas,
    bool              TemProxima,
    bool              TemAnterior);

public class PedidoOffsetService(AppDbContext context)
{
    public async Task<PaginaResultado<PedidoDto>> ListarAsync(
        PaginacaoRequest req,
        CancellationToken ct = default)
    {
        var query = context.Pedidos
            .AsNoTracking()
            .OrderBy(p => p.DataCriacao)
            .ThenBy(p => p.Id);

        // EF Core 8: ExecuteCount() separado sem materializar a coleção
        var total = await query.LongCountAsync(ct);

        var dados = await query
            .Skip(req.OffsetSeguro)
            .Take(req.TamanhoSeguro)
            .Select(p => new PedidoDto(p.Id, p.ClienteId, p.Valor, p.DataCriacao, p.Status))
            .ToListAsync(ct);

        var totalPaginas = (int)Math.Ceiling(total / (double)req.TamanhoSeguro);

        return new PaginaResultado<PedidoDto>(
            Dados:          dados,
            PaginaAtual:    req.Pagina,
            TamanhoPagina:  req.TamanhoSeguro,
            TotalRegistros: total,
            TotalPaginas:   totalPaginas,
            TemProxima:     req.Pagina < totalPaginas,
            TemAnterior:    req.Pagina > 1);
    }
}

⚠️ Atenção: Para tabelas com mais de 500k linhas, o LongCountAsync() por si só pode ser lento (table scan). Uma estratégia comum é cachear o total por 30–60 segundos, ou usar uma coluna de contagem materializada.

Estratégia 2: Keyset Pagination (Seek / WHERE-based)

Quando Usar

APIs REST com scroll infinito ou “next page” token
Tabelas com milhões de registros onde o OFFSET degrada
Feeds de dados em tempo real onde novos itens são inseridos constantemente
Exportação assíncrona de grandes volumes

Como Funciona

Em vez de dizer “pule N linhas”, você diz “me dê os registros após este ponto de referência”. O banco usa o índice diretamente para posicionar-se no cursor, sem varrer os registros anteriores.

-- SQL Server / Oracle 12c+ / PostgreSQL — keyset com chave composta
SELECT TOP(21) Id, ClienteId, Valor, DataCriacao
FROM Pedidos
WHERE DataCriacao > '2025-06-01T12:00:00'
   OR (DataCriacao = '2025-06-01T12:00:00' AND Id > 'abc-def-123')
ORDER BY DataCriacao ASC, Id ASC;

O TOP 21 (ou LIMIT 21) é intencional: busca-se um registro a mais para saber se há próxima página, sem fazer um COUNT.

Índice Obrigatório para Keyset

-- SQL Server — índice covering para a query de keyset
CREATE INDEX IX_Pedidos_Keyset
    ON Pedidos (DataCriacao ASC, Id ASC)
    INCLUDE (ClienteId, Valor, Status);

-- Oracle
CREATE INDEX IX_Pedidos_Keyset ON Pedidos (DataCriacao ASC, Id ASC);

-- PostgreSQL
CREATE INDEX IX_Pedidos_Keyset ON Pedidos (DataCriacao ASC, Id ASC)
    INCLUDE (ClienteId, Valor, Status);

Sem esse índice, o banco recai em um full scan mesmo com a cláusula WHERE do keyset.

Implementação com EF Core 8

// Token de cursor — serializado em Base64 para o cliente (opaco)
public record KeysetCursor(Guid UltimoId, DateTime UltimaData)
{
    public string Encode() =>
        Convert.ToBase64String(
            JsonSerializer.SerializeToUtf8Bytes(this));

    public static KeysetCursor? Decode(string? token)
    {
        if (string.IsNullOrEmpty(token)) return null;
        try
        {
            return JsonSerializer.Deserialize<KeysetCursor>(
                Convert.FromBase64String(token));
        }
        catch { return null; }
    }
}

public record KeysetResultado<T>(
    IReadOnlyList<T> Dados,
    bool             TemProximaPagina,
    string?          ProximoToken);   // Token opaco para o cliente

public class PedidoKeysetService(AppDbContext context)
{
    public async Task<KeysetResultado<PedidoDto>> ListarAsync(
        string?           token,
        int               limite   = 20,
        CancellationToken ct       = default)
    {
        limite = Math.Clamp(limite, 1, 100);
        var cursor = KeysetCursor.Decode(token);

        // Expressão de keyset — funciona sem cursor (primeira página)
        // e com cursor (páginas seguintes)
        var query = context.Pedidos
            .AsNoTracking()
            .Where(p =>
                cursor == null ||
                p.DataCriacao > cursor.UltimaData ||
                (p.DataCriacao == cursor.UltimaData &&
                 p.Id.CompareTo(cursor.UltimoId) > 0))
            .OrderBy(p => p.DataCriacao)
            .ThenBy(p => p.Id)
            .Select(p => new PedidoDto(p.Id, p.ClienteId, p.Valor, p.DataCriacao, p.Status));

        // Busca limite+1 para detectar se há próxima página
        var dados = await query.Take(limite + 1).ToListAsync(ct);

        var temProxima = dados.Count > limite;
        if (temProxima) dados.RemoveAt(dados.Count - 1);

        string? proximoToken = null;
        if (temProxima && dados.Count > 0)
        {
            var ultimo = dados[^1];
            proximoToken = new KeysetCursor(ultimo.Id, ultimo.DataCriacao).Encode();
        }

        return new KeysetResultado<PedidoDto>(dados, temProxima, proximoToken);
    }
}

O token gerado é opaco para o cliente — ele não sabe o que está dentro, apenas passou para a próxima chamada. Isso permite mudar a implementação interna sem quebrar os clientes.

Estratégia 3: Cursor de Banco de Dados (Server-Side Cursor)

O Que é um Cursor de Banco e Quando Usar

Um cursor de banco de dados é diferente do keyset cursor. Aqui, o próprio banco mantém uma posição de leitura aberta entre as chamadas. O servidor reserva recursos (memória, locks ou um snapshot) para aquele conjunto de resultados enquanto o cliente vai buscando blocos.

É a estratégia ideal para:

Exportações longas onde o cliente consome os dados em blocos ao longo de segundos ou minutos
Processamento ETL linha por linha sem carregar tudo na memória
Streaming de dados via WebSocket ou Server-Sent Events
Situações onde o conjunto de resultados não pode mudar durante a leitura (snapshot consistency) > ⚠️ Atenção: Cursores de banco consomem recursos do servidor enquanto estão abertos. Em SQL Server e Oracle, cursores mal gerenciados (esquecidos abertos) causam memory pressure e até bloqueios. PostgreSQL lida melhor com cursores em transações, mas ainda exige cuidado.

PostgreSQL: DECLARE CURSOR (o mais completo)

O PostgreSQL tem o suporte mais rico a cursores server-side. Para usá-los com EF Core, é necessário executar SQL raw dentro de uma transação, pois os cursores do PostgreSQL existem apenas no escopo de uma transação:

// dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
public class PedidoCursorService(AppDbContext context)
{
    public async IAsyncEnumerable<PedidoDto> StreamAsync(
        int blocoPorFetch = 500,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        // Cursor PG exige transação ativa durante toda a leitura
        await using var transaction = await context.Database
            .BeginTransactionAsync(ct);

        // DECLARE abre o cursor no servidor
        await context.Database.ExecuteSqlRawAsync(
            "DECLARE pedidos_cursor NO SCROLL CURSOR FOR " +
            "SELECT p.\"Id\", p.\"ClienteId\", p.\"Valor\", p.\"DataCriacao\", p.\"Status\" " +
            "FROM \"Pedidos\" p ORDER BY p.\"DataCriacao\", p.\"Id\"",
            ct);

        try
        {
            while (!ct.IsCancellationRequested)
            {
                // FETCH busca um bloco por vez — nunca tudo na memória
                var bloco = await context.Database
                    .SqlQueryRaw<PedidoDto>(
                        $"FETCH {blocoPorFetch} FROM pedidos_cursor")
                    .ToListAsync(ct);

                if (bloco.Count == 0) break;   // Fim do cursor

                foreach (var item in bloco)
                    yield return item;

                if (bloco.Count < blocoPorFetch) break; // Último bloco parcial
            }
        }
        finally
        {
            // CLOSE libera recursos no servidor — SEMPRE executar
            await context.Database.ExecuteSqlRawAsync(
                "CLOSE pedidos_cursor", CancellationToken.None);

            await transaction.CommitAsync(CancellationToken.None);
        }
    }
}

SQL Server: FAST_FORWARD Cursor via Raw SQL

O SQL Server suporta cursores T-SQL, mas para APIs REST o padrão mais eficiente é usar IAsyncEnumerable com AsAsyncEnumerable() do EF Core ou um cursor via ADO.NET direto:

// SQL Server: streaming com IAsyncEnumerable do EF Core 8
// Internamente usa DataReader que consome linha por linha
public class PedidoStreamService(AppDbContext context)
{
    public async IAsyncEnumerable<PedidoDto> StreamComEfCoreAsync(
        DateTime? dataInicio = null,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        // AsAsyncEnumerable() não materializa a coleção —
        // mantém o DataReader aberto e lê sob demanda
        var query = context.Pedidos
            .AsNoTracking()
            .Where(p => dataInicio == null || p.DataCriacao >= dataInicio)
            .OrderBy(p => p.DataCriacao)
            .ThenBy(p => p.Id)
            .Select(p => new PedidoDto(p.Id, p.ClienteId, p.Valor, p.DataCriacao, p.Status));

        await foreach (var item in query.AsAsyncEnumerable().WithCancellation(ct))
        {
            yield return item;
        }
    }
}

💡 Dica: AsAsyncEnumerable() no EF Core é implementado como um DataReader que permanece aberto enquanto o IAsyncEnumerable está sendo consumido. Internamente, ele funciona como um cursor de banco implicit. A diferença para um cursor SQL explícito é que o DataReader não permite pausar a leitura e retomar mais tarde em uma nova conexão.

Oracle: REF CURSOR e SYS_REFCURSOR

No Oracle, o equivalente é o REF CURSOR, geralmente exposto via stored procedure. Com o provider Oracle.EntityFrameworkCore, você pode executá-lo assim:

// Oracle: REF CURSOR via stored procedure
// A procedure retorna um SYS_REFCURSOR como parâmetro OUT
public class PedidoOracleService(AppDbContext context)
{
    public async Task<List<PedidoDto>> BuscarViaCursorAsync(
        DateTime dataInicio,
        int quantidade,
        CancellationToken ct = default)
    {
        var param_dataInicio = new OracleParameter("p_data",   OracleDbType.Date)
            { Value = dataInicio };
        var param_qtd        = new OracleParameter("p_qtd",    OracleDbType.Int32)
            { Value = quantidade };
        var param_cursor     = new OracleParameter("p_cursor", OracleDbType.RefCursor)
            { Direction = ParameterDirection.Output };

        // Chama a stored procedure que faz OPEN cursor FOR SELECT ...
        await context.Database.ExecuteSqlRawAsync(
            "BEGIN PKG_PEDIDOS.BUSCAR_PAGINADO(:p_data, :p_qtd, :p_cursor); END;",
            param_dataInicio, param_qtd, param_cursor, ct);

        // Lê o REF CURSOR retornado pelo Oracle
        var refCursor = (OracleRefCursor)param_cursor.Value;
        using var reader = refCursor.GetDataReader();

        var resultado = new List<PedidoDto>();
        while (await reader.ReadAsync(ct))
        {
            resultado.Add(new PedidoDto(
                Id:          reader.GetGuid(0),
                ClienteId:   reader.GetString(1),
                Valor:       reader.GetDecimal(2),
                DataCriacao: reader.GetDateTime(3),
                Status:      reader.GetString(4)));
        }
        return resultado;
    }
}

Estratégia 4: Time-based Pagination

Quando Usar

Dados que têm dimensão temporal natural (logs, eventos, transações)
APIs de auditoria ou histórico com filtros por janela de tempo
Quando o cliente quer dados de uma hora específica (e.g. “pedidos de ontem”)
Integração com sistemas de streaming (Kafka, Event Sourcing)

Implementação

A paginação time-based é uma forma especializada de keyset, com a coluna de data como cursor primário. A diferença é que o cliente escolhe a janela de tempo explicitamente:

public record TimePaginacaoRequest(
    DateTime  DataInicio,
    DateTime  DataFim,
    DateTime? UltimaDataVista = null,  // Cursor dentro da janela
    Guid?     UltimoIdVisto   = null,
    int       Limite          = 50);

public class PedidoTimeService(AppDbContext context)
{
    public async Task<KeysetResultado<PedidoDto>> ListarPorJanelaAsync(
        TimePaginacaoRequest req,
        CancellationToken    ct = default)
    {
        var limite = Math.Clamp(req.Limite, 1, 200);

        var query = context.Pedidos
            .AsNoTracking()
            // Janela de tempo fixa — mantém o conjunto estável
            .Where(p => p.DataCriacao >= req.DataInicio &&
                        p.DataCriacao <  req.DataFim)
            // Cursor dentro da janela (para paginação sequencial)
            .Where(p =>
                req.UltimaDataVista == null ||
                p.DataCriacao > req.UltimaDataVista ||
                (p.DataCriacao == req.UltimaDataVista &&
                 p.Id.CompareTo(req.UltimoIdVisto!.Value) > 0))
            .OrderBy(p => p.DataCriacao)
            .ThenBy(p => p.Id)
            .Select(p => new PedidoDto(p.Id, p.ClienteId, p.Valor, p.DataCriacao, p.Status));

        var dados = await query.Take(limite + 1).ToListAsync(ct);
        var temProxima = dados.Count > limite;
        if (temProxima) dados.RemoveAt(dados.Count - 1);

        string? proximoToken = null;
        if (temProxima && dados.Count > 0)
        {
            var ultimo = dados[^1];
            proximoToken = new KeysetCursor(ultimo.Id, ultimo.DataCriacao).Encode();
        }

        return new KeysetResultado<PedidoDto>(dados, temProxima, proximoToken);
    }
}

💡 Dica: A grande vantagem da paginação time-based sobre keyset puro é que o cliente pode escolher janelas imutáveis (e.g. “todo o dia 2025-01-01”), o que permite cache agressivo dessas janelas no servidor, já que o conteúdo não muda depois que a janela fecha.

Estratégia 5: Token Opaco e Link HATEOAS

Quando Usar

APIs públicas onde você não quer expor detalhes de implementação ao cliente
Quando a estratégia de paginação pode mudar sem quebrar os clientes
APIs que precisam de HATEOAS (links de próxima/anterior página na resposta) O token opaco encapsula qualquer estratégia de cursor internamente:

// Resposta no padrão HATEOAS com links de navegação
public record PaginacaoHateoasResultado<T>(
    IReadOnlyList<T> Dados,
    PaginacaoLinks   Links,
    PaginacaoMeta    Meta);

public record PaginacaoLinks(
    string?  Primeiro,
    string?  Anterior,
    string?  Proximo,
    string?  Ultimo);

public record PaginacaoMeta(
    int  Limite,
    long TotalRegistros,
    bool TemProxima);

// Endpoint que monta a resposta HATEOAS
app.MapGet("/api/v1/pedidos", async (
    HttpContext          httpCtx,
    [FromQuery] string?  cursor,
    [FromQuery] int      limite = 20,
    PedidoKeysetService  service,
    CancellationToken    ct) =>
{
    var resultado = await service.ListarAsync(cursor, limite, ct);
    var baseUrl   = $"{httpCtx.Request.Scheme}://{httpCtx.Request.Host}/api/v1/pedidos";

    return Results.Ok(new PaginacaoHateoasResultado<PedidoDto>(
        Dados:  resultado.Dados,
        Links:  new PaginacaoLinks(
            Primeiro:  $"{baseUrl}?limite={limite}",
            Anterior:  null,  // Keyset não suporta voltar sem histórico
            Proximo:   resultado.TemProximaPagina
                           ? $"{baseUrl}?cursor={resultado.ProximoToken}&limite={limite}"
                           : null,
            Ultimo:    null),
        Meta: new PaginacaoMeta(
            Limite:          limite,
            TotalRegistros:  -1,  // Keyset não calcula total
            TemProxima:      resultado.TemProximaPagina)));
});

Comparativo: Qual Estratégia Usar em Cada Situação

Critério	Offset	Keyset / Seek	Cursor Server-Side	Time-based	Token Opaco
Total de registros	✅ Sim	❌ Não	❌ Não	⚠️ Por janela	❌ Não
Salto de página	✅ Direto	❌ Apenas sequencial	❌ Apenas sequencial	✅ Por janela	❌ Apenas sequencial
Performance em pg. tardias	❌ Degrada	✅ Constante	✅ Constante	✅ Constante	✅ Constante
Registros novos entre páginas	❌ Drift	✅ Consistente	✅ Snapshot	✅ Janela fixa	✅ Consistente
Complexidade de impl.	⭐ Simples	⭐⭐ Média	⭐⭐⭐ Alta	⭐⭐ Média	⭐⭐ Média
Recursos no servidor	Baixo	Baixo	🔴 Alto (cursor aberto)	Baixo	Baixo
Suporte EF Core nativo	✅ Completo	✅ Com Where custom	⚠️ Raw SQL / ADO	✅ Com Where custom	✅ Sobre keyset
SQL Server	✅ OFFSET FETCH	✅ WHERE seek	✅ FAST_FORWARD cursor	✅ WHERE range	✅
Oracle	✅ 12c+ / ROWNUM 11g	✅ WHERE seek	✅ REF CURSOR	✅ WHERE range	✅
PostgreSQL	✅ LIMIT OFFSET	✅ WHERE seek	✅ DECLARE CURSOR	✅ WHERE range	✅
Melhor para	UI clássica	APIs / mobile	ETL / streaming	Auditoria / logs	APIs públicas

Índices: A Fundação de Toda Paginação

Nenhuma estratégia de paginação funciona bem sem os índices certos. Para cada banco:

-- ============================================
-- SQL Server — Índices para paginação
-- ============================================

-- Para Offset por DataCriacao
CREATE INDEX IX_Pedidos_DataCriacao
    ON Pedidos (DataCriacao ASC, Id ASC)
    INCLUDE (ClienteId, Valor, Status);

-- Para filtros frequentes + paginação
CREATE INDEX IX_Pedidos_ClienteId_Data
    ON Pedidos (ClienteId ASC, DataCriacao ASC, Id ASC)
    INCLUDE (Valor, Status);

-- ============================================
-- Oracle — Equivalentes
-- ============================================
CREATE INDEX IX_Pedidos_DataCriacao
    ON Pedidos (DataCriacao ASC, Id ASC);

-- Oracle: statistics importantes para o otimizador
EXECUTE DBMS_STATS.GATHER_TABLE_STATS('SCHEMA', 'PEDIDOS');

-- ============================================
-- PostgreSQL — Com partial index opcional
-- ============================================
CREATE INDEX IX_Pedidos_DataCriacao
    ON Pedidos (DataCriacao ASC, Id ASC)
    INCLUDE (ClienteId, Valor, Status);

-- Partial index para status frequente (ex.: apenas pedidos ativos)
CREATE INDEX IX_Pedidos_Ativos
    ON Pedidos (DataCriacao ASC, Id ASC)
    WHERE Status = 'Ativo';

⚠️ Atenção Oracle: O Oracle não suporta INCLUDE columns em índices regulares (diferente de SQL Server e PostgreSQL). Para covering indexes no Oracle, use Composite Indexes ou Index-Organized Tables (IOT) para tabelas de alto volume de leitura.

Middleware de Paginação Reutilizável para ASP.NET Core

Para APIs REST com múltiplos endpoints, criar um middleware de paginação evita duplicação:

// Extensions para registrar os serviços e configurar resposta padrão
public static class PaginacaoExtensions
{
    // Header padrão de paginação (common em APIs REST)
    public static IEndpointConventionBuilder ComPaginacao(
        this IEndpointConventionBuilder builder)
    {
        // Adiciona headers de documentação no OpenAPI
        builder.WithOpenApi(op =>
        {
            op.Parameters.Add(new OpenApiParameter
            {
                Name     = "cursor",
                In       = ParameterLocation.Query,
                Required = false,
                Schema   = new OpenApiSchema { Type = "string" },
                Description = "Token de cursor para próxima página (keyset pagination)"
            });
            op.Parameters.Add(new OpenApiParameter
            {
                Name     = "limite",
                In       = ParameterLocation.Query,
                Required = false,
                Schema   = new OpenApiSchema { Type = "integer", Default = new OpenApiInteger(20) }
            });
            return op;
        });
        return builder;
    }

    // Adiciona Link header HTTP padrão RFC 5988
    public static void AdicionarLinkHeader<T>(
        this HttpContext ctx,
        KeysetResultado<T> resultado,
        string baseUrl)
    {
        if (resultado.ProximoToken != null)
            ctx.Response.Headers.Append(
                "Link",
                $"<{baseUrl}?cursor={resultado.ProximoToken}>; rel=\"next\"");
    }
}

Dicas e Boas Práticas

Nunca retorne sem Take/Limit: Sempre aplique um limite máximo na camada de serviço, independente do que o cliente enviou. Exponha isso via validação de request.
Keyset exige chave composta estável: Use sempre (coluna_ordenacao, id_unico) como cursor composto. Apenas a coluna de ordenação pode ter duplicatas, o Id garante unicidade e estabilidade.
Cursor de banco: sempre feche: Para cursores server-side (PostgreSQL DECLARE, Oracle REF CURSOR), use try/finally para garantir o CLOSE. Um cursor esquecido aberto no Oracle ou SQL Server consome recursos do servidor indefinidamente.
Documente o tipo de paginação na OpenAPI: Indique no Swagger qual estratégia cada endpoint usa — clientes precisam saber se podem usar salto de página ou apenas avançar sequencialmente.
Versione a estratégia de paginação: Se você mudar de Offset para Keyset em um endpoint existente, versione a API (/v2/pedidos) para não quebrar clientes que dependem do campo totalPaginas.
Monitor de queries lentas: Ative o Query Store (SQL Server), AWR (Oracle) ou pg_stat_statements (PostgreSQL) para capturar queries de paginação que ultrapassam SLAs.
Prefira projeções com Select(): Nunca retorne a entidade completa em endpoints de listagem. Selecione apenas os campos necessários para reduzir I/O e alocação de memória.

Conclusão

Paginar dados em APIs REST com C# e EF Core 8 vai muito além de .Skip().Take(). Cada estratégia — Offset, Keyset, Cursor server-side, Time-based e Token opaco — existe por um motivo e serve a cenários distintos. A escolha errada resulta em queries lentas, inconsistências de dados ou consumo desnecessário de recursos no banco.

O caminho mais seguro é: comece com Offset para UIs simples com volumes controlados, migre para Keyset conforme a tabela cresce e o offset começa a degradar, use Cursor server-side apenas para streaming e ETL com cuidado no gerenciamento do ciclo de vida, e Time-based para dados com dimensão temporal natural.

SQL Server, Oracle e PostgreSQL suportam todas essas estratégias — as diferenças estão na sintaxe e nos detalhes de implementação, mas o EF Core 8 abstrai a maior parte delas. O que o EF Core não faz por você é criar os índices certos: essa é sempre sua responsabilidade.

Se você chegou aqui buscando entender como gargalos de banco afetam não só a leitura, mas também a escrita em massa, continue com o artigo Gargalo em Banco de Dados com C# e EF Core: Mensageria e Paginação, que aborda a solução via mensageria (RabbitMQ e Azure Service Bus) para o lado da escrita.

Referências

EF Core — Querying Data (Microsoft Docs) — Documentação oficial de consultas com EF Core
EF Core — Pagination — Guia oficial de paginação com EF Core (Offset e Keyset)
PostgreSQL — Cursors — Documentação oficial de cursores no PostgreSQL
SQL Server — Cursor T-SQL — Referência de cursores T-SQL no SQL Server
Oracle — REF CURSOR — Documentação oficial de REF CURSOR no Oracle PL/SQL
Use the PostgreSQL pg_stat_statements — Monitoramento de queries lentas no PostgreSQL
Repositório blog-zocateli-sample — Pagination — Código-fonte completo dos exemplos deste artigo 📬

👉 Artigo completo com todos os exemplos de código: Paginação em APIs REST com C# e EF Core: Guia Prático

O Projeto Fênix e a TI que eu vivo todos os dias

Lincoln Zocateli — Tue, 14 Apr 2026 01:42:47 +0000

INTRODUÇÃO

Como Solutions Architect e dev .NET há mais de 25 anos, eu já vi de tudo um pouco: times brilhantes travados por processos ruins, deploy manual virando ritual de sofrimento e decisões técnicas sendo engolidas por urgência. Foi por isso que "O Projeto Fênix", do Gene Kim, me pegou tanto — não como ficção corporativa, mas como espelho.

O livro fala sobre DevOps, fluxo e melhoria contínua, mas o que realmente me marcou foi a sensação de frustração de querer fazer certo em um ambiente que ainda não entende o básico de entrega de software.

DESENVOLVIMENTO

Quando a operação vira o gargalo

O livro deixa claro que a TI não quebra só por falta de ferramenta; ela quebra quando cada área otimiza o próprio pedaço e ninguém enxerga o fluxo inteiro.
Isso conversa diretamente com ambientes onde o dev termina o trabalho e "joga para a operação", sem ownership real.
Na prática, o custo aparece em filas, retrabalho, incidentes recorrentes e deploys que dependem de heroísmo.

DevOps não é cargo, é desenho de sistema

O ponto mais forte do livro é mostrar que DevOps não se resume a Jenkins, Kubernetes ou pipelines bonitos.
CI/CD só funciona quando existe cultura de automação, feedback rápido e responsabilidade compartilhada.
Sem isso, a esteira vira teatro: automatiza um caos que continua existindo.

Arquitetura também é gestão de fluxo

Como arquiteto, eu me identifiquei com a tensão entre padrão ideal e realidade operacional.
Não adianta desenhar uma arquitetura elegante se o time não consegue entregar com segurança, observabilidade e rollback.
Decisões técnicas boas precisam considerar lead time, risco e capacidade do time de sustentar o sistema.

O que fica depois da leitura

Melhoria contínua não é discurso: é disciplina.
Qualidade não pode ser "fase final"; precisa nascer junto com o código.
E maturidade técnica não é fazer mais coisas, mas reduzir atrito entre ideia, implementação e produção.

CONCLUSÃO

"O Projeto Fênix" funciona porque não romantiza a TI: ele mostra o preço real de ignorar fluxo, feedback e colaboração. Para mim, foi impossível não enxergar ali a rotina de muitos times que ainda vivem entre urgência, dívida técnica e processos quebrados.

No fim, a grande lição é simples: entregar software bem não é um detalhe operacional, é parte central da estratégia.

📖 Artigo completo: https://zocate.li/posts/2026/projeto-fenix-romance-ti-devops/

Forem: Lincoln Zocateli

Gargalo em Banco de Dados: Mensageria e Paginação

Introdução

O Gargalo de Escrita: Por Que Gravar Milhares de Registros Dói

O Custo Real de Cada INSERT

Particularidades: SQL Server vs Oracle

A Solução Imediata: SaveChanges em Lote com EF Core 8

ExecuteInsertAsync e BulkInsert no EF Core 8

Mensageria: A Solução Arquitetural para Gravação em Massa

Como a Mensageria Resolve o Problema

Implementação com RabbitMQ.Client

Registrando no Program.cs

RabbitMQ vs Azure Service Bus: Qual Escolher?

Implementação Equivalente com Azure Service Bus

O Gargalo de Leitura: Por Que Trazer Tudo de Uma Vez é Perigoso

O Problema da Query Sem Limite

Tipos de Paginação: Offset vs Keyset (Cursor)

Paginação por Offset: Simples e Adequada para UIs

SQL Gerado: SQL Server vs Oracle

Keyset Pagination: Alta Performance para Scroll Infinito e APIs

Juntando Tudo: A Arquitetura Completa

Dicas e Boas Práticas

Conclusão

Leia Também

Referências

pip É Lento, Poetry Complexo: UV Chegou Resolvendo o Python

Introdução

Python: Uma Breve História

Origens

Filosofia

Guido e o BDFL

Quem mantém Python hoje

Versões marcantes

Por Que Python Ganhou Tanta Notoriedade

A revolução dos dados e da IA

Adoção acadêmica

Versatilidade

Python em números (2025–2026)

O Problema Que UV Resolve

O ecossistema antes do UV

O fluxo típico antes do UV

UV: O Que É e Quem Criou

A Astral e Charlie Marsh

O que o UV faz

Velocidade

UV na Prática

Instalação

Criar um projeto novo

Adicionar dependências

Executar o projeto

Gerenciar versões do Python

Executar ferramentas sem instalar

Fluxo completo com UV

Quando Usar UV

Cenários ideais

Cenários onde ainda avaliar

Python vs C# em Aplicações Complexas

Comparativo completo

Python para aplicações arquiteturais: é possível, mas&mldr;

Onde Python vence — sem discussão

Onde C# vence — quando complexidade importa

O veredicto

Considerações Importantes

UV Ainda É Pré-1.0

O pyproject.toml Como Fonte de Verdade

UV e Docker

UV vs Cargo vs dotnet CLI

Sobre a Adoção e Comunidade

Quando Migrar e Quando Esperar

Conclusão

Referências

Zero JavaScript: CRUD Completo com Blazor WASM e Radzen

Introdução

Pré-requisitos

Criando o Projeto Blazor WASM Standalone

Scaffolding do projeto

Configurando Program.cs

Layout com Radzen

A API REST — Domínio Produtos

Configuração CORS

O `pyproject.toml` Como Fonte de Verdade