De um .Result a uma decisão de arquitetura

01 · O ponto de partida

O código como estava

public sealed class PedidosClient
{
    private readonly HttpClient _cliente = new()
    {
        BaseAddress = new Uri("https://api.exemplo.com/v1/")
    };

    public Pedido Obter(int id)
    {
        var resposta = _cliente
            .GetAsync($"/pedidos/{id}")
            .Result;

        var json = resposta.Content
            .ReadAsStringAsync()
            .Result;

        return JsonSerializer.Deserialize<Pedido>(json);
    }
}

Compilado com <Nullable>enable</Nullable>: zero erros, um aviso. O aviso está no return e é o item 6 da lista abaixo. Repare também na barra inicial em /pedidos e no new HttpClient() dentro da classe. Os dois são problemas reais, tratados nos itens 1 e 7.

02 · O que a leitura encontrou

Oito problemas no código

1. new HttpClient() por instância

   Um HttpClient por instância da classe significa um pool de conexões e uma resolução de DNS por instância. A documentação da Microsoft é explícita em dois pontos: o cliente só resolve DNS quando cria a conexão e não respeita o TTL do servidor, então mudança de endereço não é percebida; e porta TCP não é liberada na hora do fechamento, então taxa alta de criação de cliente pode esgotar as portas do sistema operacional. A recomendação é cliente de vida longa com PooledConnectionLifetime, ou cliente curto criado pelo IHttpClientFactory.

   Microsoft Learn, Guidelines for using HttpClient "HttpClient only resolves DNS entries when a connection is created. It doesn't track any time to live (TTL) durations" "TCP ports aren't released immediately after connection closure. If the rate of requests is high, the operating system limit of available ports might be exhausted."

2. O status HTTP nunca era validado

   GetAsync não lança em resposta de erro, ele devolve o status. Sem EnsureSuccessStatusCode(), o corpo do erro (uma página HTML de 500) segue para o desserializador. O sintoma que aparece no log não tem nenhuma relação com a causa.

   execução, GET que responde 500 GetAsync sem EnsureSuccessStatusCode -> nao lancou. StatusCode=500 corpo recebido: <html><body>Internal Server Error</body></html> JsonSerializer.Deserialize -> JsonException: '<' is an invalid start of a value. Path: $ | LineNumber: 0

3. Bloqueio de thread do pool sob concorrência

   .Result segura uma thread do pool durante todo o round-trip de rede, sem fazer nada. Não é deadlock no ASP.NET Core, porque não existe SynchronizationContext para capturar. Deadlock por bloqueio acontece onde há SynchronizationContext: ASP.NET clássico, WinForms, WPF. O que acontece aqui é starvation: o pool injeta threads novas devagar, e sob carga o trabalho bloqueado pode crescer mais rápido que a injeção. Sync over async é, na própria documentação da Microsoft, a causa mais comum de starvation no thread pool.

   Microsoft Learn, Debug ThreadPool starvation, com Bombardier 125 conexoes concorrentes, 10s, contra um endpoint com sync-over-async: Latency Avg 3.48s endpoint equivalente, com codigo pior: Latency Avg 15.42s mesmo cenario no endpoint assincrono: Latency Avg 532.58ms

   Os três números são do tutorial de diagnóstico da Microsoft, com a ferramenta Bombardier e 125 conexões concorrentes. É latência média, não p95. O que importa não é o valor absoluto: é a distância entre o mesmo trabalho feito bloqueando e o mesmo trabalho feito assíncrono.

   A partir do .NET 6 a heurística do pool reage mais rápido a APIs bloqueantes, o que encurta a duração do episódio. Não elimina o problema, só reduz o tempo em que ele aparece.

4. Nenhum CancellationToken

   Se o cliente desiste ou estoura o timeout, o servidor continua trabalhando até terminar. GetAsync e GetStringAsync aceitam token; o código não passava, e a assinatura pública também não permitia passar.

5. A exceção chegava embrulhada em AggregateException

   Quem chama .Result vê AggregateException. Quem usa await vê a exceção original. Todo catch (HttpRequestException) já existente deixa de pegar o erro quando alguém troca a chamada.

   execução .Result -> catch(Exception) pega: AggregateException InnerException = HttpRequestException await -> catch(Exception) pega: HttpRequestException HttpRequestException.StatusCode = 404 NotFound

6. O aviso de nulidade CS8603

   JsonSerializer.Deserialize<T> devolve T?. A função promete Pedido não nulo e devolve o que vier, inclusive nulo.

   dotnet build warning CS8603: Possible null reference return.

7. Barra inicial na URI descarta o caminho do BaseAddress

   Com BaseAddress terminando em /v1/, a URI "/pedidos/1" resolve para o caminho sem o /v1/. A versão relativa sem barra inicial mantém o caminho base. O erro não estoura: a chamada vai para a URL errada e volta 404.

   execução BaseAddress = http://127.0.0.1:5099/v1/ new Uri("/pedidos/1", BaseAddress) -> http://127.0.0.1:5099/pedidos/1 new Uri("pedidos/1", BaseAddress) -> http://127.0.0.1:5099/v1/pedidos/1

8. Desserialização sem camelCase devolve objeto vazio

   JsonSerializer.Deserialize sem opções não casa camelCase, que é o padrão de API JSON. Nada estoura: o objeto volta com valores padrão. Com os defaults web, ou com ReadFromJsonAsync, o mapeamento funciona.

   execução Deserialize<Pedido>(json) -> Pedido { Id = 0, Cliente = , Total = 0 } Deserialize com JsonSerializerDefaults.Web -> Pedido { Id = 1, Cliente = ACME, Total = 10.5 } ReadFromJsonAsync<Pedido>() -> Pedido { Id = 1, Cliente = ACME, Total = 10.5 }

03 · O resultado

O depois, arquivo por arquivo

public sealed class PedidosClient(HttpClient http, ILogger<PedidosClient> logger) : IPedidosClient
{
    private const int LimiteCorpoErro = 512;

    public async Task<Pedido?> ObterAsync(int id, CancellationToken ct)
    {
        // Relativa sem barra inicial: preserva o /v1/ do BaseAddress.
        // ResponseHeadersRead: nao carrega o corpo inteiro antes de decidir.
        using var resposta = await http.GetAsync(
            $"pedidos/{id}", HttpCompletionOption.ResponseHeadersRead, ct);

        if (resposta.StatusCode == HttpStatusCode.NotFound)
        {
            return null;
        }

        if (!resposta.IsSuccessStatusCode)
        {
            var corpo = await resposta.Content.ReadAsStringAsync(ct);
            logger.LogWarning(
                "Falha ao obter pedido {PedidoId}. Status {Status}. Corpo: {Corpo}",
                id, (int)resposta.StatusCode,
                corpo.Length > LimiteCorpoErro ? corpo[..LimiteCorpoErro] : corpo);
        }

        resposta.EnsureSuccessStatusCode();

        return await resposta.Content.ReadFromJsonAsync<Pedido>(ct)
            ?? throw new InvalidOperationException(
                $"Corpo vazio ou invalido para o pedido {id}.");
    }
}

// A assinatura declara duas coisas: que existe I/O
// e que a operacao pode ser cancelada.
// Task<Pedido?> deixa claro que "nao encontrado" e um resultado esperado.
public interface IPedidosClient
{
    Task<Pedido?> ObterAsync(int id, CancellationToken ct);
}

[ApiController]
public sealed class PedidosController(IPedidosClient pedidos) : ControllerBase
{
    // O token vem do ASP.NET Core: e o RequestAborted da requisicao.
    [HttpGet("pedidos/{id:int}")]
    public async Task<ActionResult<Pedido>> Obter(int id, CancellationToken ct)
    {
        var pedido = await pedidos.ObterAsync(id, ct);
        return pedido is null ? NotFound() : Ok(pedido);
    }
}

public sealed class PedidosApiOptions
{
    [Required]
    public Uri BaseAddress { get; set; } = default!;
}

{
  "PedidosApi": {
    "BaseAddress": "https://api.exemplo.com/v1/"
  }
}

// Falha do servico remoto nao e erro interno nosso:
// 502 quando o upstream falha, 504 quando estoura o tempo.
public sealed class UpstreamExceptionHandler(IProblemDetailsService problemDetails)
    : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext contexto, Exception excecao, CancellationToken ct)
    {
        var status = excecao switch
        {
            TimeoutRejectedException => StatusCodes.Status504GatewayTimeout,
            HttpRequestException => StatusCodes.Status502BadGateway,
            _ => 0
        };

        if (status == 0)
        {
            return false;
        }

        contexto.Response.StatusCode = status;

        return await problemDetails.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = contexto,
            Exception = excecao,
            ProblemDetails =
            {
                Status = status,
                Title = "Falha ao consultar o servico de pedidos"
            }
        });
    }
}

builder.Services
    .AddOptions<PedidosApiOptions>()
    .Bind(builder.Configuration.GetSection("PedidosApi"))
    .ValidateDataAnnotations()
    .Validate(o => o.BaseAddress is { IsAbsoluteUri: true } uri
                    && uri.AbsoluteUri.EndsWith('/'),
        "BaseAddress deve ser uma URI absoluta terminando com /, senao o caminho base e descartado.")
    .ValidateOnStart();

builder.Services
    .AddHttpClient<IPedidosClient, PedidosClient>((sp, http) =>
    {
        var opcoes = sp.GetRequiredService<IOptions<PedidosApiOptions>>().Value;
        http.BaseAddress = opcoes.BaseAddress;

        // Redundante hoje: o proprio AddStandardResilienceHandler ja desliga
        // o timeout do HttpClient. Fica explicito para documentar a intencao.
        http.Timeout = Timeout.InfiniteTimeSpan;
    })
    .AddStandardResilienceHandler(o =>
    {
        o.AttemptTimeout.Timeout = TimeSpan.FromSeconds(3);
        o.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(10);
        o.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(10);
    });

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<UpstreamExceptionHandler>();

// ...
app.UseExceptionHandler();

public sealed class PedidosClientTests
{
    private sealed class FakeHandler(
        Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> resposta)
        : HttpMessageHandler
    {
        protected override Task<HttpResponseMessage> SendAsync(
            HttpRequestMessage request, CancellationToken ct) => resposta(request, ct);
    }

    private static PedidosClient Criar(FakeHandler handler) =>
        new(new HttpClient(handler) { BaseAddress = new Uri("https://teste/v1/") },
            NullLogger<PedidosClient>.Instance);

    [Fact]
    public async Task Retorna_pedido_em_200_com_camelCase_e_url_com_v1()
    {
        Uri? uri = null;
        var cliente = Criar(new FakeHandler((req, _) =>
        {
            uri = req.RequestUri;
            return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)
            {
                Content = new StringContent(
                    """{"id":1,"cliente":"ACME","total":10.5}""",
                    Encoding.UTF8, "application/json")
            });
        }));

        var pedido = await cliente.ObterAsync(1, CancellationToken.None);

        Assert.Equal("https://teste/v1/pedidos/1", uri!.ToString());
        Assert.Equal("ACME", pedido!.Cliente);
    }

    [Fact]
    public async Task Retorna_nulo_em_404()
    {
        var cliente = Criar(new FakeHandler((_, _) =>
            Task.FromResult(new HttpResponseMessage(HttpStatusCode.NotFound))));

        Assert.Null(await cliente.ObterAsync(1, CancellationToken.None));
    }

    [Fact]
    public async Task Lanca_HttpRequestException_com_status_em_500()
    {
        var cliente = Criar(new FakeHandler((_, _) =>
            Task.FromResult(new HttpResponseMessage(HttpStatusCode.InternalServerError)
            {
                Content = new StringContent("<html>erro</html>")
            })));

        var erro = await Assert.ThrowsAsync<HttpRequestException>(
            () => cliente.ObterAsync(1, CancellationToken.None));

        Assert.Equal(HttpStatusCode.InternalServerError, erro.StatusCode);
    }

    [Fact]
    public async Task Propaga_cancelamento()
    {
        using var cts = new CancellationTokenSource();
        var cliente = Criar(new FakeHandler(async (_, ct) =>
        {
            await Task.Delay(Timeout.Infinite, ct);
            return new HttpResponseMessage(HttpStatusCode.OK);
        }));

        cts.CancelAfter(50);

        await Assert.ThrowsAnyAsync<OperationCanceledException>(
            () => cliente.ObterAsync(1, cts.Token));
    }
}

04 · Depois que entra no ar

Observabilidade

05 · As escolhas

Por que assim e não de outro jeito

• Propagar Task e token até a borda Custo: mudança em cascata nos arquivos que tocam a chamada.
• Remover a camada de serviço duplicada Custo: se surgir regra de negócio, a camada volta e o controller muda.
• 404 como retorno nulo, não como exceção Custo: todo chamador precisa tratar o nulo. Benefício: o compilador avisa, e não há exceção para um resultado esperado.
• GetAsync com ResponseHeadersRead e validação manual, em vez de GetFromJsonAsync Motivo: preciso ler e registrar o corpo do erro. Custo: esquecer EnsureSuccessStatusCode() passa a ser possível, e o teste de 500 cobre isso. Se eu não precisasse do corpo do erro, GetFromJsonAsync seria mais simples.
• Falha do upstream vira 502 ou 504 com ProblemDetails Custo: mais um componente (IExceptionHandler) e uma decisão sobre o que o cliente da minha API deve ver.
• Timeout só no resilience handler Custo: quem ler o código precisa saber que o tempo é controlado em outro lugar. A linha que zera o HttpClient.Timeout é redundante hoje, porque o próprio AddStandardResilienceHandler já faz isso, e o teste confirma o valor efetivo. Fica explícita para documentar a intenção.
• BaseAddress em configuração, validada no startup Custo: um arquivo a mais. Benefício: erro de configuração derruba o deploy, não a primeira requisição. A validação checa IsAbsoluteUri antes de tocar em AbsoluteUri, senão um valor relativo derruba com InvalidOperationException no meio da validação, em vez de mensagem de configuração.
• ReadFromJsonAsync no lugar de Deserialize Resolve camelCase e, com o ??, o aviso CS8603.
• Sem ConfigureAwait(false) na camada de aplicação Em biblioteca que roda em hosts diferentes, continua valendo.

Em cenários de alta performance, use o source generator do System.Text.Json com JsonSerializerContext para evitar reflexão.

06 · A divisão do trabalho

Onde a IA ajuda e onde a decisão continua minha

07 · Conclusão

O que sobra deste caso

A IA acelera a descoberta e a execução. A decisão, o teste e a revisão continuam comigo.

Fontes