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

-- 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;

// ❌ 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();

-- 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;

// 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);
    }
}

-- 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;

-- 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);

// 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);
    }
}

// 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: 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;
        }
    }
}

// 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;
    }
}

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);
    }
}

// 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)));
});

-- ============================================
-- 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';

// 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\"");
    }
}