Pular para o conteúdo principal
Versão: 10.4.1

ADR 001 — Sem wrappers de framework no DevPack

Status: Accepted
Data: 2026-04-23

Contexto​

O ITLab.Template.DevPack é um pacote NuGet compartilhado que serve como esqueleto técnico para projetos nascidos do ITLab.Template. Durante a extração do DevPack a partir do ITLab.WorkGuardian.SharedKernel, surgiu a questão de até onde o pacote deveria ir: apenas abstrações e utilitários genéricos, ou também wrappers sobre frameworks como EF Core, Serilog, SignalR, etc.

Decisão​

O DevPack não cria wrappers sobre frameworks externos. Ele expõe diretamente as dependências de framework com as quais os projetos consumidores devem interagir.

Exemplos do que o DevPack faz:

  • Expõe interfaces genéricas (IRepository<T>, IUnitOfWork, ICurrentUser, IDateTimeProvider)
  • Fornece behaviors de pipeline Mediator (ValidationPipelineBehavior, RequestLoggingPipelineBehavior, NormalizeDateTimeOffsetBehavior)
  • Fornece interceptors EF Core base (AuditableEntityInterceptor, SoftDeleteInterceptor, DispatchDomainEventsInterceptor)
  • Oferece extensões utilitárias puras (DateTimeOffsetExtensions, StringExtensions, GuardExtensions, etc.)
  • Exporta classes de AppSettings tipadas com IAppOptions (ApplicationOptions, JwtOptions, LdapOptions, etc.)

Exemplos do que o DevPack não faz:

  • Não cria ILogger<T> wrappers — os consumidores usam o Serilog/Microsoft.Extensions.Logging diretamente
  • Não cria abstrações sobre IMemoryCache além das extensões utilitárias já existentes
  • Não cria factories ou builders para registrar serviços no DI — cada projeto tem seu próprio Program.cs
  • Não encapsula HttpClient, IEmailSender, ISlackClient atrás de interfaces adicionais — as abstrações genéricas de notificação (NotificationRecipientDto, ENotificationFormat) são suficientes

Justificativa​

  1. Acoplamento desnecessário: wrappers adicionam uma camada indirecta que dificulta debugging e aumenta a superfície de testes sem agregar valor real.

  2. Vazamento de abstração: frameworks como EF Core, Serilog e SignalR têm APIs ricas e bem documentadas. Wrappers simplificados invariavelmente limitam o acesso a recursos avançados.

  3. Facilidade de atualização: sem wrappers, atualizar a versão de uma dependência de framework exige apenas bumpar o número de versão no ITLab.Template.DevPack.csproj, sem reescrever código intermediário.

  4. Princípio de menor surpresa: consumidores que já conhecem os frameworks não precisam aprender uma API adicional específica do DevPack.

Consequências​

  • Projetos consumidores importam e usam os frameworks diretamente, o que é esperado e documentado.
  • O DevPack foca em ser um ponto de entrada consistente (convenções, behaviors, interceptors, configurações) sem ser um invólucro completo.
  • Novos tipos adicionados ao DevPack devem passar pelo critério: "isso seria útil em qualquer projeto .NET do ITLab, independente do domínio de negócio?" Se a resposta for não, pertence ao projeto específico, não ao DevPack.