Tooark.Dtos 4.1.0

Tooark.Dtos

Biblioteca para gerenciamento e manutenção de DTOs base em projetos .NET.

Conteúdo

• Visão Geral
• Instalação
• Configuração
• Componentes
• Exemplos de Uso
• Dependências
• Contribuição
• Licença

Visão Geral

O pacote Tooark.Dtos fornece:

• DTOs de busca e paginação para endpoints de listagem;
• uma resposta padrão com dados, erros, paginação e metadados;
• tradução automática das chaves de erro produzidas pelas validações do Tooark;
• limite de tamanho de página, para que uma requisição não possa pedir todos os registros.

Requisito de runtime: SearchDto, PaginationDto e ResponseDto usam tipos do MVC, do Http e do WebUtilities, então o pacote exige o runtime do ASP.NET Core instalado. É o esperado para DTOs de API.

🔧 Instalação

dotnet add package Tooark.Dtos

⚙️ Configuração

A tradução das mensagens não exige configuração: o ResponseDto resolve o idioma pelo fluxo de execução da requisição e lê as traduções dos arquivos distribuídos com o Tooark.Extensions.

O registro abaixo existe para a aplicação poder injetar IStringLocalizer nos próprios tipos:

using Tooark.Dtos.Injections;

builder.Services.AddTooarkDtos();

Para acrescentar ou sobrescrever traduções, coloque um Resources/{idioma}.json na saída da aplicação.

📦 Componentes

Dto

Classe base dos DTOs que produzem mensagens traduzidas. Não tem membros públicos: serve para o ResponseDto e o SearchDto compartilharem o localizador.

SearchDto

Parâmetros de busca com paginação.

SearchOrderDto

Herda de SearchDto e acrescenta ordenação.

PaginationDto

Total de registros e navegação entre páginas. Todas as propriedades são somente leitura.

ResponseDto<T>

Resposta padrão de API.

Errors e Metadata são coleções somente leitura: convertê-las para IList compila, mas alterá-las lança NotSupportedException. Use SetMetadata ou AddMetadata.

MetadataDto

Par chave/valor. Chave e valor são independentes — informar um como nulo resulta em string vazia, sem descartar o outro.

Limite de tamanho de página

Sem um teto, uma única requisição poderia pedir todos os registros. O PageSize é limitado a DefaultPageSizeMax, que vale 100. Um endpoint que precise de páginas maiores sobrescreve o limite no próprio DTO:

public sealed class RelatorioSearchDto : SearchDto
{
  protected override long PageSizeMax => 5000;
}

Use a forma de expressão. Uma propriedade automática com inicializador não serve: o limite é consultado pelo construtor da classe base, que roda antes dos inicializadores da classe derivada.

Links de paginação

Os links reaproveitam a query string da requisição, trocando apenas o PageIndex, para que os filtros do endpoint sigam valendo na navegação.

Duas consequências que valem conhecer:

• Todo parâmetro da requisição aparece no corpo da resposta. Não trafegue credenciais na query string — elas voltariam nos links e daí para logs, cache e histórico do navegador.
• Os links não são um controle de acesso. Quem consegue chamar uma página consegue chamar as outras editando a URL, e o Total já informa quantas existem. Contra coleta em massa, o que vale é o teto de PageSize, o limite de taxa e a autorização — não esconder os links.

📝 Exemplos de Uso

Busca com paginação

using Microsoft.AspNetCore.Mvc;
using Tooark.Dtos;

[HttpGet]
public async Task<IActionResult> Listar([FromQuery] SearchDto filtro)
{
  var query = _context.Pessoas.AsQueryable();

  if (!string.IsNullOrEmpty(filtro.SearchNormalized))
  {
    query = query.Where(p => p.NomeNormalizado.Contains(filtro.SearchNormalized));
  }

  var total = await query.LongCountAsync();

  var pessoas = await query
    .Skip((int)(filtro.PageIndexLogical * filtro.PageSize))
    .Take((int)filtro.PageSize)
    .ToListAsync();

  var resposta = new ResponseDto<List<Pessoa>>(pessoas);
  resposta.SetPagination(new PaginationDto(total, filtro, Request));

  return Ok(resposta);
}

A resposta:

{
  "data": [ ... ],
  "errors": [],
  "pagination": {
    "total": 95,
    "pageSize": 10,
    "pageIndex": 9,
    "previous": 8,
    "next": 10,
    "currentLink": "https://api.exemplo.com/pessoas?PageIndex=9&PageSize=10",
    "previousLink": "https://api.exemplo.com/pessoas?PageIndex=8&PageSize=10",
    "nextLink": "https://api.exemplo.com/pessoas?PageIndex=10&PageSize=10"
  },
  "metadata": []
}

Não chame o parâmetro de search. O SearchDto tem uma propriedade Search, e o ASP.NET Core emite o aviso MVC1004 quando o nome do parâmetro coincide com o de uma propriedade do tipo vinculado, porque a resolução de prefixo fica ambígua. Qualquer outro nome resolve.

Busca com ordenação

using Tooark.Dtos;

[HttpGet]
public IActionResult Listar([FromQuery] SearchOrderDto filtro)
{
  var query = _context.Pessoas.OrderByProperty(filtro.OrderBy ?? nameof(Pessoa.Nome));

  // ...
}

Resposta com erros de validação

using Tooark.Dtos;

var pessoa = new Pessoa(nome, email);

// A notificação inválida vira a lista de erros, já traduzida
if (!pessoa.IsValid)
{
  // ["O campo Nome é obrigatório"]
  return BadRequest(new ResponseDto<Pessoa>(pessoa));
}

Com o código do erro na frente da mensagem:

// ["T.VLD.STR5: O campo Nome é obrigatório"]
return BadRequest(new ResponseDto<Pessoa>(pessoa.Notification, withCode: true));

Endpoint com página maior

using Tooark.Dtos;

public sealed class ExportacaoSearchDto : SearchDto
{
  protected override long PageSizeMax => 5000;
}

[HttpGet("exportacao")]
public IActionResult Exportar([FromQuery] ExportacaoSearchDto filtro)
{
  // filtro.PageSize aceita até 5000 neste endpoint
}

Metadados

using Tooark.Dtos;

var resposta = new ResponseDto<List<Pessoa>>(pessoas);

resposta.AddMetadata(new MetadataDto("versao", "2024-01"));
resposta.SetMetadata([new MetadataDto("origem", "cache")]);

📋 Dependências

🪪 Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues e pull requests no repositório Tooark.Dtos.

📄 Licença

Este projeto está licenciado sob a licença BSD 3-Clause. Veja o arquivo LICENSE para mais detalhes.