Skip to content

biellts/universidade-automatiza / .claude/skills/backend-criar-consulta-dapper

backend-criar-consulta-dapper

Verified

Cria a consulta de leitura de um caso de uso com Dapper e SQL explícito sobre o PostgreSQL da aplicação, qualificado pelo schema do módulo. Use quando solicitado a criar listagem, detalhe, busca, filtro ou paginação.

Criar consulta Dapper

Leitura não passa pelo agregado nem pelo EF: SQL explícito, visível na revisão, executado com Dapper sobre a conexão de IConexaoProvider.

Local

Dentro do slice do caso de uso:

src/apps/Automatiza.Modules.{Modulo}/Features/{Entidade}s/UseCases/{CasoDeUso}/
  {X}Request.cs        ← record : IQuery<Result<T>>
  {X}QueryHandler.cs   ← abre a conexão e executa o SQL
  {X}Endpoint.cs
  {X}Response.cs
  {X}Query.cs          ← só o SQL (internal static class com const string Sql)

Regras

  • SQL em public const string Sql dentro de internal static class {X}Query, com raw string literal (""").
  • Tabelas sempre qualificadas pelo schema do módulo (catalogo.trilhas). Nunca leia tabela de outro schema nem faça JOIN entre schemas de módulos diferentes — use a interface pública do outro módulo.
  • Colunas em snake_case; o Dapper casa com as propriedades PascalCase do record por DefaultTypeMap.MatchNamesWithUnderscores = true (já ligado em AddDataBase). Não precisa de alias AS.
  • Parâmetros sempre nomeados (@Id, @Publico, @Limite); nunca concatenação ou interpolação de valores.
  • CommandDefinition com cancellationToken.
  • Conexão por IConexaoProvider.Criar() com await using (o Dapper abre a conexão sozinho).
  • Enum filtrado em coluna smallint: envie o parâmetro como short ((short?)request.Publico), senão o PostgreSQL compara smallint com integer e não usa o índice. Na leitura, o enum : short casa direto.
  • Datas timestamptz chegam em DateTimeOffset pelo DateTimeOffsetTypeHandler (já registrado). Sempre UTC; a conversão para o horário de Brasília só acontece onde a regra pede (ver skill dotnet-timezone).
  • Paginação com LIMIT @Limite OFFSET @Deslocamento, ordenação determinística (ORDER BY + desempate por id) e COUNT(*) com o mesmo filtro no mesmo comando (QueryMultipleAsync), devolvendo PaginatedResponse<T> (Automatiza.SeedWork.Models). Limite o tamanho da página com uma constante no request.
  • Somente SELECT. Nenhum INSERT, UPDATE, DELETE ou DDL: escrita é pelo agregado; schema é pela migration.
  • Dado de tenant (quando o módulo Empresas existir): o filtro por tenant_id é obrigatório no SQL — o Dapper não passa pelo filtro global do EF Core.
  • Nenhum registro no DI: a classe de SQL é estática e o handler é registrado pelo AddCustomMediator.

Exemplo real (Catálogo — ListarTrilhas)

ListarTrilhasQuery.cs:

namespace Automatiza.Modules.Catalogo.Features.Trilhas.UseCases.ListarTrilhas;

internal static class ListarTrilhasQuery
{
    public const string Sql = """
        SELECT COUNT(*)
          FROM catalogo.trilhas
         WHERE (@Publico IS NULL OR publico = @Publico);

        SELECT id, titulo, publico, funcao_alvo
          FROM catalogo.trilhas
         WHERE (@Publico IS NULL OR publico = @Publico)
         ORDER BY titulo, id
         LIMIT @Limite OFFSET @Deslocamento;
        """;
}

ListarTrilhasQueryHandler.cs:

namespace Automatiza.Modules.Catalogo.Features.Trilhas.UseCases.ListarTrilhas;

public class ListarTrilhasQueryHandler(IConexaoProvider conexaoProvider)
    : Handler<ListarTrilhasRequest, Result<PaginatedResponse<ListarTrilhasItemResponse>>>
{
    public override async Task<Result<PaginatedResponse<ListarTrilhasItemResponse>>> OnHandle(ListarTrilhasRequest request, CancellationToken cancellationToken)
    {
        var tamanho = Math.Clamp(request.PageSize, 1, ListarTrilhasRequest.TamanhoMaximoPagina);
        var pagina = Math.Max(request.PageIndex, 0);

        await using var conexao = conexaoProvider.Criar();

        // smallint no banco: o parâmetro precisa ir como short, senão o PostgreSQL compara smallint com integer sem índice.
        var parametros = new
        {
            Publico = (short?)request.Publico,
            Limite = tamanho,
            Deslocamento = pagina * tamanho
        };

        using var leitor = await conexao.QueryMultipleAsync(
            new CommandDefinition(ListarTrilhasQuery.Sql, parametros, cancellationToken: cancellationToken));

        var total = await leitor.ReadSingleAsync<long>();
        var itens = await leitor.ReadAsync<ListarTrilhasItemResponse>();

        return new PaginatedResponse<ListarTrilhasItemResponse>(pagina, tamanho, total, itens);
    }
}

Detalhe por Id (ObterTrilhaPorId): QuerySingleOrDefaultAsync<ObterTrilhaPorIdResponse> com new { request.Id }; null vira TrilhaErrors.TrilhaNaoEncontrada.Format(request.Id.ToString()), que o endpoint devolve como 404.

internal static class ObterTrilhaPorIdQuery
{
    public const string Sql = """
        SELECT id, titulo, descricao, publico, funcao_alvo, criado_em
          FROM catalogo.trilhas
         WHERE id = @Id
        """;
}

Teste

Todo SQL novo tem teste de integração via ApplicationFactory (Testcontainers PostgreSQL, migrations aplicadas na subida), chamando o endpoint. O banco é compartilhado pela classe de teste: crie os dados com um sufixo único (Guid.NewGuid().ToString("N")[..8]) e filtre por ele — nunca dependa de tabela vazia. Ver TrilhasTests.Listar_FiltrandoPorPublico_TrazSoAsDoPublicoOrdenadasPorTitulo. Regras gerais: AGENTS.md.

deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall