Forem: Bruno Silva

Migrando do AutoMapper para Mapster em .NET: Segurança, Performance e Custo Zero

Bruno Silva — Thu, 26 Mar 2026 13:12:26 +0000

Fala, pessoal! 👋

Hoje o papo é sobre uma mudança que muitos times estão enfrentando: a substituição do tradicional AutoMapper, por outro pacote, aqui e eu optei pelo Mapster e vou contar como foi o processo de migração, por que decidimos sair do AutoMapper e como o Mapster pode ser um aliado para manter sua aplicação rápida, segura e, o melhor, sem custos adicionais. Bora conferir? 😉

O Cenário: Por que mudar?

O AutoMapper sempre foi o padrão de mercado, mas o cenário mudou drasticamente por dois motivos principais:

Vulnerabilidade Crítica: A versão 13 (gratuita) do AutoMapper apresenta vulnerabilidades conhecidas que podem comprometer a segurança da aplicação.
Mudança de Licenciamento: As novas versões corrigidas e estáveis do AutoMapper passaram a adotar um modelo pago, o que pode inviabilizar a migração para muitos projetos e empresas.

Diante disso, precisávamos de uma alternativa que fosse open-source (MIT), mantivesse a produtividade do time e, se possível, trouxesse ganhos de performance. Foi aí que o Mapster entrou em cena. 🚀

Por que Mapster?

O Mapster não é apenas um "substituto", ele é uma evolução em vários aspectos:

✅ Performance Extrema: Ele gera código otimizado em tempo de execução (JIT) ou compilação, sendo significativamente mais rápido que o AutoMapper.
✅ Memória Otimizada: Consome menos recursos, o que é vital para microsserviços e APIs de alta escala.
✅ Sintaxe Familiar: Se você já usa AutoMapper, vai se sentir em casa. A curva de aprendizado é baixíssima.
✅ Sem Herança Obrigatória: Você não precisa herdar de classes como Profile para tudo, embora possa organizar seus mapeamentos de forma similar.

Mão na Massa: Implementação

1. Instalação dos Pacotes

dotnet add package Mapster
dotnet add package Mapster.DependencyInjection

2. Configurando o Mapeamento (O novo "Profile")

No Mapster, utilizamos a interface IRegister. Veja como fica um mapeamento genérico de um DTO de usuário:

public class UsuarioMapping : IRegister
{
    public void Register(TypeAdapterConfig config)
    {
        config.NewConfig<Usuario, UsuarioDto>()
            .Map(dest => dest.NomeCompleto, src => $"{src.FirstName} {src.LastName}")
            .Map(dest => dest.DataCadastro, src => src.CreatedAt)
            .Ignore(dest => dest.SenhaHash) // Segurança em primeiro lugar!
            .AfterMapping((src, dest) => {
                // Lógica customizada pós-mapeamento
                dest.UltimoAcesso = DateTime.Now;
            });
    }
}

3. Registro na Injeção de Dependência

No seu Program.cs, a configuração é muito limpa. Ele faz o scan automático de todos os seus mapeamentos:

// Registra o Mapster
var config = TypeAdapterConfig.GlobalSettings;
config.Scan(Assembly.GetExecutingAssembly());

builder.Services.AddSingleton(config);
builder.Services.AddScoped<IMapper, ServiceMapper>();

Diferenças Práticas: De AutoMapper para Mapster

Para facilitar a sua vida na hora de converter os mapeamentos, aqui está um "de-para" rápido das operações que mais usamos no dia a dia:

1. Configuração Inicial

No AutoMapper, herdamos de Profile. No Mapster, implementamos IRegister.

AutoMapper: public class MyProfile : Profile
Mapster: public class MyMapping : IRegister

2. Mapeamento de Membros

A sintaxe muda de .ForMember para um simples .Map.

AutoMapper:

.ForMember(dest => dest.Nome, opt => opt.MapFrom(src => src.FullName))

Mapster:

.Map(dest => dest.Nome, src => src.FullName)

3. Ignorar Campos

Mais direto e sem a necessidade de abrir uma expressão de opção.

AutoMapper:

.ForMember(dest => dest.Senha, opt => opt.Ignore())

Mapster:
```
.Ignore(dest => dest.Senha)
```

4. Lógica Pós-Mapeamento

O AfterMap vira AfterMapping.

AutoMapper:

.AfterMap((src, dest) => dest.Data = DateTime.Now)

Mapster:

.AfterMapping((src, dest) => {
    dest.Data = DateTime.Now;
})

5. Mapeamento de Mão Dupla

Se você precisa que o mapeamento funcione nos dois sentidos (Src -> Dest e Dest -> Src).

AutoMapper: .ReverseMap()
Mapster: .TwoWays()

Uso no Dia a Dia (Services/Controllers)

O uso continua sendo via injeção de dependência, o que significa que você quase não altera seu código de negócio:

public class PedidoService
{
    private readonly IMapper _mapper;

    public PedidoService(IMapper mapper)
    {
        _mapper = mapper;
    }

    public async Task<PedidoDto> ProcessarPedido(Pedido pedido)
    {
        // A chamada é idêntica!
        var dto = _mapper.Map<PedidoDto>(pedido);
        return dto;
    }
}

Resultados Obtidos

Após a migração, notamos benefícios imediatos:

Segurança: Vulnerabilidades da versão gratuita do AutoMapper eliminadas.
Compliance: Sem preocupações com custos inesperados de licenciamento.
Velocidade: Redução perceptível no tempo de processamento de mapeamentos complexos em listas grandes.

Conclusão

Mudar de biblioteca nem sempre é uma escolha fácil, mas quando envolve segurança e sustentabilidade financeira do projeto, é uma decisão necessária. O Mapster provou ser uma ferramenta superior em performance e extremamente amigável para quem está vindo do ecossistema AutoMapper.

Se você está rodando versões antigas do AutoMapper, recomendo fortemente avaliar essa migração. É o tipo de melhoria técnica que "se paga" no primeiro deploy.

Espero que esse guia ajude vocês nessa jornada! Dúvidas? Deixa nos comentários! 👇

#backend #mapping #mapster #dotnet #braziliandevs #performance #security #opensource

Cache Multi-Nível com FusionCache em Aplicações .NET 8

Bruno Silva — Fri, 26 Sep 2025 00:49:56 +0000

Fala, pessoal! 👋
Hoje falar um papo sobre cache multi-nível e como implementar isso de forma prática usando o FusionCache.

A ideia é mostrar como deixar sua aplicação mais rápida, resiliente e preparada para lidar com cenários de alta demanda. Bora lá? 😉

Antes de ir para o código, precisamos entender os conceitos.

O que é Cache Multi-Nível?

Cache multi-nível é uma arquitetura que combina diferentes tipos de cache para otimizar performance:

L1 (Level 1): Cache em memória local - ultra-rápido (~0.1ms)
L2 (Level 2): Cache distribuído (Redis/Valkey) - rápido e compartilhado (~1-5ms)

Por exemplo, em APIs podemos usar cache L1 para dados acessados frequentemente e cache L2 para compartilhar dados entre múltiplas instâncias da aplicação.

Por que FusionCache?

O FusionCache é uma biblioteca .NET que oferece:

✅ Cache Multi-Nível (L1 + L2 automático)
✅ Backplane (sincronização entre instâncias)
✅ Fail-Safe (funciona mesmo se Redis cair)
✅ Cache Stampede Protection (evita sobrecarga)
✅ Timeouts Configuráveis (performance otimizada)

Cenário de Exemplo

Vamos imaginar uma API que precisa trabalhar com cache, mas diferenciando entre dois tipos de dados: críticos e simples.

Mas por que separar assim? 🤔
A ideia é ter mais controle sobre o tempo de vida de cada cache de acordo com a importância da informação e isso era uma necessidade real que eu tinha.

Crítico: dados muito requisitados (coisa de 1 milhão de requisições por dia) e que mudam pouco. Aqui vale a pena usar L1 + L2, garantindo performance máxima e resiliência.
Simples: dados menos importantes, que não precisam ficar tanto tempo em memória. Nesse caso podemos buscar mais vezes no Redis/Valkey, usando principalmente o L2.

Implementação em .NET 8

1. Instalação dos Pacotes NuGet

dotnet add package ZiggyCreatures.FusionCache
dotnet add package ZiggyCreatures.FusionCache.Serialization.NewtonsoftJson
dotnet add package ZiggyCreatures.FusionCache.Backplane.StackExchangeRedis

2. Configuração no Program.cs

// Configuração do Redis/Valkey
builder.Services.AddSingleton<IConnectionMultiplexer>(sp =>
{
    var connectionString = builder.Configuration.GetConnectionString("Redis") ?? "localhost:6379";
    var configurationOptions = ConfigurationOptions.Parse(connectionString);
    configurationOptions.AbortOnConnectFail = false;
    configurationOptions.ConnectRetry = 1;
    configurationOptions.ConnectTimeout = 1000;
    configurationOptions.SyncTimeout = 3000;

    return ConnectionMultiplexer.Connect(configurationOptions);
});

// Cache distribuído (L2)
builder.Services.AddSingleton<IDistributedCache>(sp =>
{
    var redis = sp.GetRequiredService<IConnectionMultiplexer>();
    return new RedisCache(new RedisCacheOptions
    {
        ConnectionMultiplexerFactory = () => Task.FromResult(redis),
        InstanceName = ""
    });
});

// FusionCache Crítico (L1 + L2 + Backplane) - Para produtos
builder.Services.AddFusionCache("CacheCritico")
    .WithDefaultEntryOptions(new FusionCacheEntryOptions
    {
        Duration = TimeSpan.FromMinutes(10),           // L1: 10 minutos
        DistributedCacheDuration = TimeSpan.FromMinutes(30), // L2: 30 minutos
        FactorySoftTimeout = TimeSpan.FromMilliseconds(100),
        FactoryHardTimeout = TimeSpan.FromSeconds(2),
        IsFailSafeEnabled = true,
        FailSafeMaxDuration = TimeSpan.FromHours(2),
        FailSafeThrottleDuration = TimeSpan.FromSeconds(30)
    })
    .WithSerializer(new FusionCacheNewtonsoftJsonSerializer())
    .WithDistributedCache(sp => sp.GetRequiredService<IDistributedCache>())
    .WithBackplane(new RedisBackplane(new RedisBackplaneOptions
    {
        Configuration = builder.Configuration.GetConnectionString("Redis")
    }));

// FusionCache Simples (microcaching + L2) - Para relatórios
builder.Services.AddFusionCache("CacheSimples")
    .WithDefaultEntryOptions(new FusionCacheEntryOptions
    {
        Duration = TimeSpan.FromSeconds(30),          // L1: 30 segundos (microcaching)
        DistributedCacheDuration = TimeSpan.FromMinutes(60), // L2: 60 minutos
        FactorySoftTimeout = TimeSpan.FromMilliseconds(200),
        FactoryHardTimeout = TimeSpan.FromSeconds(5),
        IsFailSafeEnabled = true,
        FailSafeMaxDuration = TimeSpan.FromHours(1),
        FailSafeThrottleDuration = TimeSpan.FromSeconds(15)
    })
    .WithSerializer(new FusionCacheNewtonsoftJsonSerializer())
    .WithDistributedCache(sp => sp.GetRequiredService<IDistributedCache>())
    .WithBackplane(new RedisBackplane(new RedisBackplaneOptions
    {
        Configuration = builder.Configuration.GetConnectionString("Redis")
    }));

var app = builder.Build();

Aqui estamos registrando o FusionCache e dizendo que ele vai usar tanto memória local quanto Redis como backplane. Simples, né? 😎

3. Interface de Cache Personalizada

public interface ICacheService
{
    Task<T> BuscarAsync<T>(string chave);
    Task CriarAsync<T>(string chave, T valor, TimeSpan? expiracao = null);
    Task<T> BuscarOuCriarAsync<T>(string chave, Func<Task<T>> factory, TimeSpan? expiracao = null);
    Task RemoverAsync(string chave);
    Task<bool> ExisteAsync(string chave);
    Task RemoverPorPrefixoAsync(string prefixo);
}

4. Implementação do Serviço de Cache

public class FusionCacheService : ICacheService
{
    private readonly IFusionCache _cacheCritico;
    private readonly IFusionCache _cacheSimples;
    private readonly IConnectionMultiplexer _connectionMultiplexer;
    private readonly IDatabase _database;

    public FusionCacheService(
        IFusionCacheProvider fusionCacheProvider,
        IConnectionMultiplexer connectionMultiplexer)
    {
        _cacheCritico = fusionCacheProvider.GetCache("CacheCritico");
        _cacheSimples = fusionCacheProvider.GetCache("CacheSimples");
        _connectionMultiplexer = connectionMultiplexer;
        _database = connectionMultiplexer?.GetDatabase(0);
    }

    public async Task<T> BuscarAsync<T>(string chave)
    {
        var cache = EscolherCache(chave);
        return await cache.GetOrDefaultAsync<T>(chave);
    }

    public async Task CriarAsync<T>(string chave, T valor, TimeSpan? expiracao = null, TimeSpan? expiracaoMemoria = null)
    {
        var cache = EscolherCache(chave);
        var options = new FusionCacheEntryOptions();

        if (expiracao.HasValue)
        {
            options.DistributedCacheDuration = expiracao.Value;
        }
        if (expiracaoMemoria.HasValue)
        {
            options.Duration= expiracaoMemoria.Value;
        }

        await cache.SetAsync(chave, valor, options);
    }

    public async Task<T> BuscarOuCriarAsync<T>(string chave, Func<Task<T>> factory, TimeSpan? expiracao = null, TimeSpan? expiracaoMemoria = null)
    {
        var cache = EscolherCache(chave);
        var options = new FusionCacheEntryOptions();

        if (expiracao.HasValue)
        {
            options.DistributedCacheDuration = expiracao.Value;
        }
        if (expiracaoMemoria.HasValue)
        {
            options.Duration= expiracaoMemoria.Value;
        }

        return await cache.GetOrSetAsync<T>(chave, async (ctx, token) => await factory(), options);
    }

    public async Task RemoverAsync(string chave)
    {
        // Remove de ambos os caches (ativa Backplane automaticamente)
        await _cacheCritico.RemoveAsync(chave);
        await _cacheSimples.RemoveAsync(chave);
    }

    public async Task<bool> ExisteAsync(string chave)
    {
        var cache = EscolherCache(chave);
        var valor = await cache.GetOrDefaultAsync<object>(chave);
        return valor != null;
    }

    public async Task RemoverPorPrefixoAsync(string prefixo)
    {
        if (_connectionMultiplexer?.IsConnected == true)
        {
            var server = _connectionMultiplexer.GetServer(_connectionMultiplexer.GetEndPoints().First());
            var pattern = $"*{prefixo}*";

            // Busca chaves com SCAN e remove via FusionCache (ativa Backplane)
            await foreach (var chaveRedis in server.KeysAsync(pattern: pattern))
            {
                var chaveLimpa = ExtrairChaveFusionCache(chaveRedis);
                await _cacheCritico.RemoveAsync(chaveLimpa);
                await _cacheSimples.RemoveAsync(chaveLimpa);
            }
        }
    }

    /// <summary>
    /// Escolhe qual tipo de cache usar baseado na criticidade dos dados
    /// </summary>
    private IFusionCache EscolherCache(string chave)
    {
        // Dados críticos: usa cache completo (L1 + L2)
        if (chave.StartsWith("produto:") || chave.StartsWith("usuario:"))
            return _cacheCritico;

        // Dados menos críticos: usa microcaching + L2
        return _cacheSimples;
    }

    /// <summary>
    /// Remove prefixo de versão do FusionCache (v0:, v1:, etc.)
    /// </summary>
    private string ExtrairChaveFusionCache(RedisKey chaveRedis)
    {
        var chaveStr = chaveRedis.ToString();

        var indiceDoisPontos = chaveStr.IndexOf(':');
        if (indiceDoisPontos > 0)
        {
            var possivelPrefixo = chaveStr.Substring(0, indiceDoisPontos + 1);

            // Verifica se é prefixo de versão (v + números + :)
            if (possivelPrefixo.StartsWith("v") && possivelPrefixo.EndsWith(":"))
            {
                var numeroVersao = possivelPrefixo.Substring(1, possivelPrefixo.Length - 2);
                if (numeroVersao.All(char.IsDigit))
                {
                    return chaveStr.Substring(possivelPrefixo.Length);
                }
            }
        }

        return chaveStr;
    }
}

5. Configuração no appsettings.json

{
  "ConnectionStrings": {
    "Redis": "localhost:6379"
  },
  "Cache": {
    "Tipo": "FusionCache"
  }
}

6. Uso nos Controllers

Agora vamos ver como aplicar estratégias de cache diferentes nos nossos Controllers.

👉 Obs: no exemplo vou mostrar direto na Controller só pra facilitar o entendimento.
Mas, seguindo boas práticas, o ideal é ter uma camada de Services responsável pelo acesso aos dados, deixando a Controller apenas como “ponte” entre requisição e regra de negócio.

No primeiro endpoint temos cache de produtos críticos com L1 + L2.

No segundo endpoint foi implementado cache de relatórios com microcaching.

No terceiro endpoint mostramos remoção por prefixo para invalidar categorias inteiras.

Código do Controller:

[ApiController]
[Route("api/[controller]")]
public class ProdutosController : ControllerBase
{
    private readonly ICacheService _cache;
    private readonly IProdutoRepository _produtoRepository;

    public ProdutosController(ICacheService cache, IProdutoRepository produtoRepository)
    {
        _cache = cache;
        _produtoRepository = produtoRepository;
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> BuscarProduto(int id)
    {
        // Cache crítico - L1 (10min) + L2 (20min)
        var produto = await _cache.BuscarOuCriarAsync(
            $"produto:{id}",
            async () => await _produtoRepository.BuscarPorIdAsync(id),
            TimeSpan.FromMinutes(20),
            TimeSpan.FromMinutes(10)
        );

        return Ok(produto);
    }

    [HttpGet("categoria/{categoriaId}")]
    public async Task<IActionResult> BuscarProdutosPorCategoria(int categoriaId)
    {
        // Cache simples - Microcaching (30s) + L2 (60min)
        var produtos = await _cache.BuscarOuCriarAsync(
            $"categoria:{categoriaId}",
            async () => await _produtoRepository.BuscarPorCategoriaAsync(categoriaId)
        );

        return Ok(produtos);
    }

    [HttpPost("{id}")]
    public async Task<IActionResult> AtualizarProduto(int id, [FromBody] Produto produto)
    {
        // Atualiza no banco
        await _produtoRepository.AtualizarAsync(produto);

        // Remove cache específico (ativa Backplane - sincroniza todas as instâncias)
        await _cache.RemoverAsync($"produto:{id}");

        // Remove caches relacionados por prefixo
        await _cache.RemoverPorPrefixoAsync($"produtos:categoria:{produto.CategoriaId}");

        return Ok();
    }

    [HttpGet("relatorio/vendas")]
    public async Task<IActionResult> RelatorioVendas()
    {
        // Relatório - Cache simples com TTL longo
        var relatorio = await _cache.BuscarOuCriarAsync(
            "relatorio:vendas:diario",
            async () => await GerarRelatorioVendas(),
            TimeSpan.FromHours(1), TimeSpan.FromMinutes(30)
        );

        return Ok(relatorio);
    }

    private async Task<object> GerarRelatorioVendas()
    {
        // Simula processamento pesado
        await Task.Delay(2000);
        return new { 
            TotalVendas = 15000m, 
            Data = DateTime.Now,
            TotalProdutos = 150 
        };
    }
}

Principais Benefícios Obtidos

Performance Dramática

Cache Hit L1: ~0.1ms (1000x mais rápido que banco)
Cache Hit L2: ~2ms (50x mais rápido que banco)
Cache Miss: Tempo normal do banco

Sincronização Entre Instâncias

// Problema antes do Backplane:
// Instância A: Remove cache às 10:30
// Instância B: Cache válido até 10:35 (5 min desatualizado!)

// Solução com Backplane:
// Instância A: Remove cache às 10:30
// Backplane: Notifica TODAS as instâncias instantaneamente
// Instância B: Remove cache automaticamente às 10:30
// ✅ Todas as instâncias sincronizadas!

Resiliência Total

// Cenário: Redis fica offline
// ✅ L1 (memória) continua funcionando
// ✅ Fail-Safe serve dados em cache mesmo expirados
// ✅ Aplicação NÃO para, NÃO trava
// ✅ Quando Redis volta, reconecta automaticamente

Configurações Avançadas

Cache por Tipo de Dados

private IFusionCache EscolherCache(string chave)
{
    // Dados críticos: L1 + L2 completo
    if (chave.StartsWith("produto:") || 
        chave.StartsWith("usuario:") || 
        chave.StartsWith("config:"))
        return _cacheCritico;

    // Dados menos críticos: microcaching + L2
    return _cacheSimples;
}

TTL Diferenciado

// Cache crítico com TTL otimizado
await _cache.CriarAsync("produto:123", produto,
    TimeSpan.FromMinutes(30),    // L2: 30 minutos
    TimeSpan.FromMinutes(5)    // L1:5 minutos
);

// Cache de relatório com TTL longo
await _cache.CriarAsync("relatorio:vendas", relatorio,
    TimeSpan.FromHours(4),    // L2: 4 horas
    TimeSpan.FromMinutes(1)   // L1: 1 Minuto (microcaching)
);

Remoção Inteligente por Prefixo

public async Task AtualizarCategoria(int categoriaId)
{
    // Atualiza dados no banco
    await _repository.AtualizarCategoria(categoriaId);

    // Remove TODOS os caches relacionados (em TODAS as instâncias)
    await _cache.RemoverPorPrefixoAsync($"produtos:categoria:{categoriaId}");

    // Próximas consultas já pegam dados atualizados!
}

Exemplo de Teste no Swagger

Teste 1: Cache Hit

GET /api/produtos/123
Response Time: 0.2ms ← Cache L1

Teste 2: Cache Miss → Cache Hit

GET /api/produtos/456
Response Time: 150ms ← Busca no banco

GET /api/produtos/456 (segunda chamada)
Response Time: 0.2ms ← Cache L1

Teste 3: Sincronização Between Instâncias

Instância A: POST /api/produtos/123 (atualiza produto)
Backplane: Sincroniza remoção automaticamente

Instância B: GET /api/produtos/123
Response: Dados atualizados! ✅

Resultados Obtidos

Performance

95% redução no tempo de resposta para dados em cache
80% redução na carga do banco de dados
Sub-segundo response time para a maioria das consultas

Resiliência

100% uptime mesmo com falhas do Redis
Zero downtime durante manutenções do cache
Fail-safe mantém aplicação funcionando

Escalabilidade

Sincronização automática entre N instâncias
Load balancer friendly (cache consistente)
Zero configuração adicional para novas instâncias

Configuração de Fallback

Para desenvolvimento ou quando Redis não está disponível:

// Fallback automático para cache apenas em memória
try
{
    // Configuração com Redis (produção)
    ConfigurarFusionCacheComRedis();
}
catch (Exception)
{
    // Fallback para apenas memória (desenvolvimento)
    services.AddFusionCache()
        .WithDefaultEntryOptions(new FusionCacheEntryOptions
        {
            Duration = TimeSpan.FromMinutes(10)
            // Sem DistributedCache nem Backplane
        });
}

Conclusão

O FusionCache oferece uma solução para cache em aplicações .NET 8:

✅ Zero breaking changes no código existente

✅ Performance extrema com cache multi-nível

✅ Sincronização automática entre instâncias

✅ Resiliência total a falhas de infraestrutura

✅ Configuração flexível por tipo de dados

Esta implementação é ideal para:

APIs de alta performance
Aplicações distribuídas
Microserviços que precisam de cache consistente

Com essas configurações, você consegue ter cache que melhora drasticamente a performance e reduz a carga no banco de dados, enquanto mantém dados sempre sincronizados entre todas as instâncias!

Simples né? Com apenas essas configurações você consegue ter uma solução de cache robusta, performática e resiliente.

Espero que tenham gostado e até a próxima!

#backend #cache #fusionCache #dotnet #braziliandevs #performance #redis #valkey

Implementando Resiliência em Aplicações .NET 8 com Polly

Bruno Silva — Tue, 02 Sep 2025 14:15:08 +0000

Hoje vamos falar sobre resiliência em aplicações e como implementar políticas de retry, circuit breaker e outras técnicas usando a biblioteca Polly no .NET 8.

O que é Resiliência em Software?

Resiliência em software é a capacidade de uma aplicação continuar funcionando adequadamente mesmo quando enfrenta falhas temporárias ou problemas de infraestrutura. Em um mundo de microserviços e APIs distribuídas, falhas transitórias são comuns - timeouts de rede, serviços temporariamente indisponíveis, limitações de taxa (rate limiting), entre outros.

O que é o Polly?

Polly é uma biblioteca .NET que permite implementar políticas de resiliência e tratamento de falhas transitórias de forma elegante e configurável. Com Polly, você pode adicionar comportamentos como:

Retry: Tentar novamente após uma falha
Circuit Breaker: Evitar chamadas quando um serviço está falhando consistentemente
Timeout: Definir tempo limite para operações
Fallback: Comportamento alternativo em caso de falha
Bulkhead Isolation: Isolar recursos para evitar propagação de falhas
Cache: Armazenar resultados para evitar chamadas desnecessárias

Por que adotar o Polly?

Antes de adotarmos o Polly, lidávamos com falhas transitórias em nosso código de forma manual e pouco estruturada.
Um exemplo era o uso de goto para implementar tentativas de repetição (retry) em chamadas onde um token vencia e precisva pegar um novo. Apesar de funcionar em alguns cenários, essa abordagem tornava o código difícil de ler, de manter e de evoluir.

O Polly surgiu como uma alternativa muito mais limpa, flexível e padronizada. Com ele conseguimos substituir blocos de código complexos (e até "gambiarras") por políticas declarativas, configuráveis e fáceis de entender.
Isso trouxe vários benefícios:

Legibilidade: O código ficou mais claro e expressivo.
Padronização: Passamos a tratar falhas de forma consistente em diferentes partes da aplicação.
Evolução: É simples trocar ou combinar políticas (ex.: Retry + Circuit Breaker) sem precisar reescrever a lógica do zero.
Manutenção: Reduzimos a chance de erros escondidos em tratamentos manuais.

Instalação

Para começar a usar o Polly em seu projeto .NET 8, instale o pacote NuGet:

dotnet add package Polly
dotnet add package Microsoft.Extensions.Http.Polly

Implementação Prática

Vamos criar exemplos práticos de como usar o Polly em diferentes cenários.

1. Retry Simples

Começando com um exemplo básico de retry:

using Polly;

public class ProdutoService
{
    private readonly HttpClient _httpClient;

    public async Task<Produto> ObterProdutoAsync(int id)
    {
        // Define política de retry: 3 tentativas
        var retryPolicy = Policy
            .Handle<HttpRequestException>()
            .RetryAsync(3, onRetry: (exception, retryCount) =>
            {
                Console.WriteLine($"Tentativa {retryCount} falhou: {exception.Message}");
            });

        // Executa com a política
        return await retryPolicy.ExecuteAsync(async () =>
        {
            var response = await _httpClient.GetAsync($"/api/produtos/{id}");
            response.EnsureSuccessStatusCode();
            return await response.Content.ReadFromJsonAsync<Produto>();
        });
    }
}

2. Wait and Retry com Backoff Exponencial

Para cenários mais complexos, podemos usar wait-and-retry com intervalos crescentes:

public class NotaFiscalService
{
    private readonly HttpClient _httpClient;
    private readonly ILogger<NotaFiscalService> _logger;

    public async Task<NotaFiscalResponse> EmitirNotaAsync(NotaFiscalRequest request)
    {
        var retryPolicy = Policy
            .HandleResult<HttpResponseMessage>(r => !r.IsSuccessStatusCode)
            .WaitAndRetryAsync(
                retryCount: 4,
                sleepDurationProvider: retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)),
                onRetry: (outcome, timespan, retryCount, context) =>
                {
                    var statusCode = outcome.Result?.StatusCode;
                    _logger.LogWarning(
                        "Tentativa {RetryCount} após {Timespan}s. StatusCode: {StatusCode}",
                        retryCount, timespan.TotalSeconds, statusCode);
                });

        var response = await retryPolicy.ExecuteAsync(async () =>
            await _httpClient.PostAsJsonAsync("/api/nfe/emitir", request)
        );

        return await response.Content.ReadFromJsonAsync<NotaFiscalResponse>();
    }
}

3. Renovação Automática de Token com Retry

Um cenário muito comum é renovar tokens JWT automaticamente quando expiram:

public class ApiClientService
{
    private readonly HttpClient _httpClient;
    private readonly ITokenService _tokenService;
    private string _currentToken;

    public async Task<T> ExecutarRequisicaoAsync<T>(string endpoint)
    {
        var retryPolicy = Policy<HttpResponseMessage>
            .HandleResult(r => r.StatusCode == HttpStatusCode.Unauthorized)
            .RetryAsync(
                retryCount: 3,
                onRetryAsync: async (outcome, retryCount, context) =>
                {
                    Console.WriteLine($"Token expirado. Renovando... Tentativa {retryCount}/3");

                    // Renova o token
                    _currentToken = await _tokenService.RenovarTokenAsync();

                    // Atualiza o header de autorização
                    _httpClient.DefaultRequestHeaders.Authorization = 
                        new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", _currentToken);
                });

        var response = await retryPolicy.ExecuteAsync(async () =>
        {
            var request = new HttpRequestMessage(HttpMethod.Get, endpoint);
            request.Headers.Authorization = 
                new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", _currentToken);

            return await _httpClient.SendAsync(request);
        });

        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<T>();
    }
}

Boas Práticas

Escolha as políticas adequadas: Nem toda operação precisa de retry. Operações não-idempotentes devem ser tratadas com cuidado.
Configure timeouts apropriados: Evite que retries demorem muito tempo.
Use Circuit Breaker para dependências externas: Proteja sua aplicação de serviços instáveis.
Monitore e registre logs: Acompanhe quantos retries estão ocorrendo.

Conclusão

O Polly é uma ferramenta poderosa para adicionar resiliência às suas aplicações .NET. Com apenas algumas linhas de código, você pode tornar sua aplicação muito mais robusta e capaz de lidar com falhas transitórias de forma elegante.
A implementação de políticas de resiliência não é apenas uma boa prática - é essencial em arquiteturas distribuídas modernas. Com o Polly, você tem um kit de ferramenta completo para implementar padrões de resiliência de forma simples e manutenível.

Espero que este artigo tenha sido útil para entender como implementar resiliência em suas aplicações .NET 8!

dotnet #polly #resilience #microservices #braziliandevs

Implementação de RateLimit em Aplicações .NET 8

Bruno Silva — Fri, 16 Feb 2024 01:43:22 +0000

Hoje vamos falar um pouco sobre Ratelimit e aproveitar para mostrar como fazer a implementação em uma aplicação Net 8.

Antes de ir pra código precisamos entender.

O que é RateLimit?

Este termo "rate limit" é referente a um mecanismo usado para controlar a taxa de solicitações de requisições que um usuário pode realizar em um determinado período de tempo.

Por exemplo, em APIs podemos impor limites de taxa para evitar que um único cliente ou aplicativo sobrecarregue o servidor com um grande número de solicitações em um curto período de tempo. E isso pode ser feito através do "Rate Limit".

Em resumo, o rate limit é uma técnica utilizada para garantir que um serviço ou recurso não seja sobrecarregado, equilibrando a carga e garantindo um desempenho consistente e justo para todos os usuários, limitando assim o número de solicitações que podem ser feitas por segundo, minuto, hora etc.

Os bloqueios podem ser feitos por usuário , ip de origem, endpoint , enfim as possibilidades são inúmeras.

Implementação em .NET 8

A partir do .net 7 a Microsoft disponibilizou um middleware nativo para implementação de limite de requisições.

Foram disponibilizadas 4 alternativas de limites:

Fixed window - (Janela fixa de tempo, neste cenário limitamos a quantidade de requisições em um determinado tempo. Ex: 5 requisições a cada 10 segundos )
Sliding window - (Janela variável de tempo. É semelhante ao limitador de janela fixa, mas adiciona segmentos por janela. A janela desliza um segmento a cada intervalo de segmento. O intervalo de segmento é (tempo de janela)/(segmentos por janela))
Token bucket - Simplificando é como se fosse um balde de tokens. Você tem uma quantidade de tokens em um balde e a cada requisição um token é retirado. A cada período os tokens também são adicionados e se em certo momento não tiver token disponível é porque atingiu a capacidade máxima.
Concurrency - Limitação por simultaneidade, ele limita a quantidade simultâneas de requisições.

Caso queira se aprofundar em mais detalhes segue o documentação da Microsoft

https://learn.microsoft.com/en-us/aspnet/core/performance/rate-limit?view=aspnetcore-8.0#fixed

Então para exemplificar vamos criar uma Api em .net 8 com alguns endpoints para simular.

Vamos focar nas opções mais usadas que é a fixed window e concurrency e vamos deixar nossa Api com 3 configurações distintas.

Bora pro código?

Para habilitar o Ratelimit na sua Api vamos ter que adicionar o método AddRateLimiter no builder.Service da sua classe program.

Neste método é possível configurar várias opções do ratelimit, a primeira configuração que vamos fazer é padronização do retorno do status code da requisição quando tivermos o limite atingindo. Para essa configuração basta associar o status 429 (too many request) a configurações opt.RejectionStatusCode.

Vamos separar nosso RateLimit em 3 opções.

Global: Vamos ter uma limitação por usuário e endpoint onde a quantidade limite de requisições seja 120 requisições por minuto.
Politica Por IP: Criaremos uma politica onde a limitação será por usuário e endpoint e a quantidade de requisições não pode passar de 50 requisições por minuto.
Politica Por Concorrência: vamos criar uma limitação onde o endpoint só pode receber 1 requisição por vez.

Politica Global:
A configuração GlobalLimiter será definida com o tipo Fixed Window , no GetFixedWindowLimiter precisamos ajustar a partition key (essa partition key é como será agrupada as nossas requisições. No nosso exemplo vamos agrupar por usuário logado e endpoint).
No retorno desse método vamos definir as configurações.

AutoReplenishment = true, //autoincremento
PermitLimit = 120, // limite de requisição
QueueLimit = 0,// limite de requisições em fila
Window =TimeSpan.FromSeconds(60) // janela de tempo

Politica Por Ip:
Um pouco mais abaixo vamos adicionar uma politica nova como o código addPolicy, definindo o nome da politica e colocando o partitionKey por Ip e Endpoint. Vamos retornar as configurações de 50 requisições por minuto.

Politica por Concorrência:
A configuração por concorrência segue os mesmos passos com algumas modificações. A adição da politica é igual então vamos fazer o addPolicy com o nome concurrency, porem o RateLimitPartition precisar ser o método GetConcurrencyLimiter. No GetConcurrencyLimiter vamos definir a partitionKey apenas por endpoint e o PermitiLimit vamos definir apenas 1, para que a limite de requisição seja apenas 1. O QueueLimit será 0 para não enfileirar nenhum request.

A ultima configuração que vamos fazer é a padronização da mensagem de retorno. Fazemos isso no OnRejected. Desta forma temos uma mensagem mais amigável de retorno.

Após as configurações feitas temos que ativar o rateLimite adicionando o codigo app.UseRateLimiter().

Lembrando que a adição desse trecho de código tem que ficar após o app.UseRouting(). Se colocado antes o Rate limit pode não funcionar.

A classe program vai ficar com as informações abaixo


builder.Services.AddRateLimiter(opt =>
{
    opt.RejectionStatusCode = StatusCodes.Status429TooManyRequests; //força o retorno 429 de too many requests
    opt.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(httpContext =>
        RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: $"{httpContext.User.Identity?.Name}_{httpContext.Request.Path}",
            factory: partion =>
            {
                return new FixedWindowRateLimiterOptions
                {
                    AutoReplenishment = true, //autoincremento 
                    PermitLimit = 120, // limite de requisição
                    QueueLimit = 0,// limite de requisições em fila
                    Window = TimeSpan.FromSeconds(60) // janela de tempo
                };
            })
    );

    opt.AddPolicy("ip", httpContext =>
       RateLimitPartition.GetFixedWindowLimiter(
           partitionKey: $"{httpContext.Request.Path}_{httpContext.Connection.RemoteIpAddress}",
           factory: partition =>
           {
               return new FixedWindowRateLimiterOptions
               {
                   AutoReplenishment = true,
                   PermitLimit = 50,
                   QueueLimit = 0,
                   Window = TimeSpan.FromSeconds(60)
               };
           }));
    opt.AddPolicy("concurrency", httpContext =>
        RateLimitPartition.GetConcurrencyLimiter(
            partitionKey: httpContext.Request.Path,
            factory: partition =>
            {
                return new ConcurrencyLimiterOptions { 
                    PermitLimit = 1,
                    QueueLimit = 0,
                };
            }));


    opt.OnRejected = async (context, token) =>
    {
        context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;
        if (context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAtfer))
            await context.HttpContext.Response.WriteAsync($"O limite de requisições foi atingifo tente novamente daqui {retryAtfer.TotalSeconds} segundos ");
        else if (context.Lease.TryGetMetadata(MetadataName.ReasonPhrase, out var reasonPhrase))
            await context.HttpContext.Response.WriteAsync($"O limite de requisições simultâneas foi atingido,tente novamente mais tarde");
        else
            await context.HttpContext.Response.WriteAsync("O limite de requisições foi atingido, tente novamente mais tarde");
    };
});

var app = builder.Build();

app.UseHttpsRedirection();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseCors(x => x
    .AllowAnyOrigin()
    .AllowAnyMethod()
    .AllowAnyHeader()
);

app.UseRateLimiter();
app.UseEndpoints(endpoints => { _ = endpoints.MapControllers(); });
app.UseResponseCompression();
app.Run();

Agora temos que configurar as nossas Controllers, lembrando que como temos uma politica global todas os endpoints já nasceram com a politica Global aplicadaa. Vamos ter que nos preocupar em configurar apenas as politicas de concorrência e por Ip

No primeiro endpoint temos o exemplo da rateLimite global, onde não há nenhuma atributo vinculado.

No Segundo endpoint foi adicionado o atributo [EnableRateLimiting("ip")], aqui o endpoint é forçado a usar a politica por IP.

No terceiro Endpoint foi adicionado o atributo [EnableRateLimiting("concurrency")], aqui o endpoint é forçado a usar a politica por concorrência.

Código Controller

  public class ExamplesController : ControllerBase
  {


      [HttpPost]
      [Route("rate-limiting-global")]
      public IActionResult ReteLimitingGlobal()
      {
          Thread.Sleep(10000);
          return Ok();
      }

      [HttpGet]
      [EnableRateLimiting("ip")]
      [Route("rate-limiting")]
      public IActionResult RateLimitingIP()
      {
          Thread.Sleep(10000);
          return Ok();
      }

      [HttpPost]
      [EnableRateLimiting("concurrency")]
      [Route("rate-limiting-post")]
      public IActionResult ReteLimitingPost()
      {
          Thread.Sleep(10000);
          return Ok();
      }

Ex: de uma chamada com limite atingido no Swagger

Simples né com apenas essas configurações você consegue ter N possibilidades de deixar sua api mais segura com controle de requisições. Isso ajuda a evitar ataques DDoS e ataques de força bruta.

Espero que tenham gostado e até a próxima!

Múltiplas documentações em uma única Api - Swagger

Bruno Silva — Fri, 29 Apr 2022 00:54:20 +0000

Bem vindos Devs!

Pensei nesse post devido a necessidade que tive esses dias e por causa da dificuldade de achar algo claro sobre o assunto.

A ideia é vir aqui de vez em quando pra mostrar alguma ideia ou algo que precisamos no dia a dia e que tenha poucos exemplos.

Bora para o que interessa, hoje vamos falar de documentação de API!!

A documentação de Api é algo muito importante nos dias de hoje e uma das ferramentas mais utilizada é o Swagger.

Em muitos cenários precisamos ter uma documentação interna para os desenvolvedores e outra para cliente/fornecedores que precisam consumir as nossas Apis.

Que tal eu mostrar uma forma simples e rápida de separar métodos e ter duas documentações diferentes de uma mesma api utilizando o Swagger?

Mas antes de começar, você sabe o que é Swagger?

O Swagger é framework de código aberto que auxilia os desenvolvedores a documentar uma API automaticamente. Sua interface gráfica possui ferramentas que deixam a visualização mais intuitiva, mostrando os métodos, parâmetros, retornos e modelos de body.

Além dessa documentação é possível também consumir os endpoints fazendo chamadas diretamente nas rotas. Desta forma você consegue testar de uma forma simplificada sem ter a necessidade de usar algum software especifico.

Agora que sabemos o que é o Swagger, vou mostrar na prática como gerar duas documentações diferentes.

Bora Codar!!!
Vamos criar uma aplicação em .net 6 e simular uma Api de produtos com 2 métodos um de buscar produto e outro de atualizar preço do produto.

Neste cenário queremos que as 2 rotas apareça para a documentação dos desenvolvedores, mas para os clientes apareçam apenas a rota de buscar produto.

Primeiro passo é ir na sua classe de controller e adicionar a ação
[ApiExplorerSettings(GroupName = "CLIENTE")]
no método que você quer disponibilizar para o cliente

Essa ação será responsável pela visibilidade dessa rota apenas para os cliente. Não é possível adicionar mais de uma ação, então iremos marcar essa api apenas para os clientes e vamos tratar para aparecer para os desenvolvedores de outra forma.

Trecho do código da controller

namespace WebApplication1.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class ProdutosController : ControllerBase
    {
        [ApiExplorerSettings(GroupName = "CLIENTE")]
        [HttpGet("buscar")]
        public IEnumerable<Produtos> BuscarProduto()
        //...

        [HttpPost("atualizar-preco")]
        public ActionResult BuscarPreco([FromBody] Produtos produto)
         //...

    }
}

Depois de configurado a controller vamos para a configuração do Swagger

Na classe Program onde é adicionado o serviço do Swagger devemos adicionar o seguinte código.

builder.Services.AddSwaggerGen(option => {
    option.SwaggerDoc("Cliente", new OpenApiInfo { Title = "Produtos API", Version = "v1" }); 
    option.SwaggerDoc("Desenvolvedor", new OpenApiInfo { Title = "Produtos API", Version = "v1" });
    option.DocInclusionPredicate((docName, apiDesc) => {
        if (docName == "Desenvolvedor")
            return true;

        var groupName = apiDesc?.GroupName;
        return groupName?.Trim().ToUpper() == docName.Trim().ToUpper();
    });
});

As linhas do SwaggerDoc é a adição das duas documentações uma para o desenvolvedor e outra para o cliente.

A linha DocInclusionPredicate é a onde fazemos a mágica (lembra que falei que iriamos tratar a visibilidade dos desenvolvedores de outra forma? então ela acontece aqui!).

Dentro do DocInclusionPredicate efetuamos uma validação, onde caso o docName seja Desenvolvedor já retorne True. Isto fará com que todos os métodos sejam mapeados para a documentação desenvolvedor na parte gráfica do Swagger.

Caso não seja a documentação do desenvolvedor ele irá validar se o docNome é igual ao GroupName definido lá na método da controller

Para finalizar podemos definir urls diferentes para cada documentação. Isso é feito também na classe Program

Antes do app.Run()

app.UseSwagger(c => c.RouteTemplate = "/swagger-desenvolvedor/{documentName}/swagger.json");
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("../swagger-desenvolvedor/Desenvolvedor/swagger.json", "Produtos API");
    c.RoutePrefix = "swagger-desenvolvedor";
});

app.UseSwagger(c => c.RouteTemplate = "/swagger-cliente/{documentName}/swagger.json");
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("../swagger-cliente/Cliente/swagger.json", "Produtos API");
    c.RoutePrefix = "swagger-cliente";
});

app.Run();

Na linha app.UseSwagger deve ser definido o caminho do json.
Na linha app.SwaggerUI deve ser adicionado o mesmo caminho do json do swagger + o nome da aplicação + a rota da url.

Defini as rotas como swagger-desenvolvedor e swagger-cliente

Pronto sua api já está com a documentação segmentada, como podemos ver abaixo a rota atualizar-preço não aparece na documentação de clientes.

A intenção do post é mostrar uma forma simplificada, existem algumas outras formas de customizar a UI do Swagger.

Espero que tenham gostado. Até a próxima!