Blog

Uma busca não tem apenas dois resultados: como pensar nos estados de uma aplicação

Uma aplicação precisa saber o que está acontecendo, não apenas se deu certo ou errado.

7 min de leiturapor Leonardo Padilha
Capa do artigo Uma busca não tem apenas dois resultados: como pensar nos estados de uma aplicação

Imagine que você está desenvolvendo uma tela para consultar pedidos de uma loja virtual.

O usuário digita o número do pedido, clica em pesquisar e aguarda o resultado.

Parece simples. A aplicação faz uma requisição, recebe os dados e mostra o pedido na tela.

Mas existe um detalhe: e quando a requisição ainda não terminou? E quando não existe nenhum pedido com aquele número? E quando o servidor está indisponível?

É nesse momento que uma lógica aparentemente simples começa a ficar mais interessante.

O problema de pensar apenas em sucesso e erro

É comum começar uma implementação pensando em apenas duas possibilidades:

  • A informação foi encontrada.

  • A informação não foi encontrada.

Só que uma aplicação real possui mais situações do que essas.

Uma busca pode estar aguardando uma resposta, pode ter sido concluída sem resultados ou pode ter falhado por algum problema de comunicação.

Se não considerarmos essas possibilidades, acabamos criando telas confusas, mensagens incorretas e comportamentos inesperados.

Por exemplo, mostrar "Nenhum pedido encontrado" enquanto a requisição ainda está sendo processada não é apenas um problema visual. É uma falha na lógica da aplicação.

Primeiro, vamos organizar o raciocínio

Antes de escrever código, podemos identificar os estados possíveis da nossa busca:

  1. Inicial: ninguém realizou uma pesquisa ainda.

  2. Carregando: a aplicação está aguardando a resposta.

  3. Sucesso: a pesquisa foi concluída e encontrou pedidos.

  4. Vazio: a pesquisa terminou, mas nenhum pedido foi encontrado.

  5. Erro: não foi possível concluir a operação.

Perceba que não estamos falando de cinco funcionalidades diferentes. Estamos falando de cinco situações possíveis de uma mesma funcionalidade.

Essa distinção ajuda a evitar condições espalhadas pelo código e torna mais fácil entender o comportamento esperado em cada situação.

Aplicando isso no React

Vamos utilizar um exemplo com React e TypeScript.

Primeiro, podemos representar os estados da busca:

type SearchState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T[] }
  | { status: "empty" }
  | { status: "error"; message: string };

Aqui estamos utilizando uma Discriminated Union, um recurso do TypeScript que permite representar diferentes possibilidades por meio de uma propriedade discriminadora.

Isso significa que cada estado possui suas próprias informações.

Por exemplo, uma busca concluída com sucesso possui uma lista de dados. Já um erro possui uma mensagem.

Também estamos evitando combinações inconsistentes, como uma operação marcada simultaneamente como carregando e concluída com erro.

Agora podemos renderizar a interface de acordo com o estado:

function assertNever(value: never): never {
  throw new Error(`Estado não tratado: ${value}`);
}

function OrderResults({
  state
}: {
  state: SearchState<Order>
}) {
  switch (state.status) {
    case "idle":
      return <p>Pesquise um pedido para começar.</p>;

    case "loading":
      return <p>Buscando pedidos...</p>;

    case "success":
      return <OrderList orders={state.data} />;

    case "empty":
      return <p>Nenhum pedido encontrado.</p>;

    case "error":
      return <p>Erro: {state.message}</p>;

    default:
      return assertNever(state);
  }
}

O componente não precisa descobrir sozinho o que aconteceu com a requisição. Ele recebe uma informação clara e apresenta a resposta correspondente.

A função assertNever também ajuda a garantir que todos os estados sejam tratados. Se adicionarmos uma nova possibilidade à nossa Union Type e esquecermos de contemplá-la no componente, o TypeScript poderá apontar essa inconsistência durante a compilação.

Para manter o exemplo focado na modelagem dos estados, estamos separando a lógica responsável pela consulta da parte responsável pela renderização. Nosso componente recebe o estado atual e decide o que apresentar na interface.

Isso deixa a renderização mais previsível e facilita a manutenção.

E como fica essa lógica no C#?

O mesmo raciocínio pode ser aplicado no backend.

Imagine que temos um serviço responsável por consultar pedidos.

Em vez de retornar apenas uma lista vazia quando algo dá errado, podemos representar explicitamente os resultados possíveis da operação.

Uma maneira de fazer isso em C# é utilizando tipos derivados de um registro abstrato:

public abstract record SearchResult<T>;

public record SearchSuccess<T>(T Data)
    : SearchResult<T>;

public record SearchEmpty<T>()
    : SearchResult<T>;

public record SearchFailure<T>(string Error)
    : SearchResult<T>;

Agora temos três possibilidades distintas:

  • SearchSuccess: a consulta foi concluída e encontrou resultados.

  • SearchEmpty: a consulta foi concluída, mas não encontrou resultados.

  • SearchFailure: ocorreu uma falha durante a operação.

Essa estrutura evita combinações contraditórias, como retornar um resultado marcado como sucesso e, ao mesmo tempo, apresentar uma mensagem de erro.

Uma implementação simplificada poderia ser:

public async Task<SearchResult<List<Order>>> SearchOrders(
    string customerId)
{
    try
    {
        var orders = await repository
            .GetByCustomerAsync(customerId);

        if (orders.Count == 0)
        {
            return new SearchEmpty<List<Order>>();
        }

        return new SearchSuccess<List<Order>>(orders);
    }
    catch (OperationCanceledException)
    {
        throw;
    }
    catch (Exception ex)
    {
        logger.LogError(
            ex,
            "Erro ao consultar pedidos do cliente {CustomerId}",
            customerId
        );

        return new SearchFailure<List<Order>>(
            "Não foi possível consultar os pedidos."
        );
    }
}

Nesse exemplo, estamos considerando que o repositório sempre retorna uma lista, mesmo quando não encontra resultados.

Também estamos tratando o cancelamento de maneira diferente das demais exceções. Isso é importante porque uma operação cancelada não significa necessariamente que ocorreu uma falha na aplicação.

As exceções são registradas para que possamos investigar o problema, enquanto a mensagem retornada ao consumidor evita expor detalhes internos da aplicação.

Em uma aplicação real, o tratamento de exceções deve ser mais específico. Nem toda exceção precisa ser convertida em um resultado de falha. Algumas devem ser propagadas para uma camada superior, dependendo da responsabilidade de cada componente.

O importante é não tratar uma lista vazia como se fosse automaticamente um erro.

Frontend e backend precisam ter os mesmos estados?

Uma observação interessante é que os exemplos anteriores não possuem exatamente a mesma quantidade de estados.

No React, temos cinco possibilidades. No C#, temos três.

Isso não representa uma inconsistência.

O frontend precisa lidar tanto com o ciclo de vida da interação quanto com o resultado da operação.

Por exemplo:

  • idle representa uma interação que ainda não começou.

  • loading representa uma requisição em andamento.

  • success, empty e error representam os possíveis resultados da consulta.

Já o backend está preocupado principalmente em representar o resultado da operação executada.

Não existe uma obrigação de compartilhar exatamente a mesma estrutura entre as duas camadas. O importante é que cada uma represente corretamente as situações pelas quais é responsável.

Por que isso faz diferença?

Quando começamos a pensar nos estados possíveis de uma aplicação, algumas decisões ficam mais simples:

  • Evitamos apresentar mensagens incorretas.

  • Reduzimos condições conflitantes.

  • Facilitamos a criação de testes.

  • Deixamos os componentes mais previsíveis.

  • Melhoramos a comunicação entre frontend e backend.

Existe ainda um benefício importante: quando surge uma nova situação, como uma busca cancelada, conseguimos avaliar onde ela se encaixa sem precisar reconstruir toda a funcionalidade.

Quando não precisamos fazer isso?

Nem toda operação precisa de cinco estados diferentes.

Uma função simples que verifica se um número é positivo, por exemplo, provavelmente não precisa de uma estrutura tão elaborada.

A ideia não é transformar qualquer trecho de código em uma máquina de estados.

É reconhecer quando uma funcionalidade possui diferentes situações que precisam ser tratadas de maneira independente.

A modelagem deve acompanhar a complexidade real do problema, e não o contrário.

Para finalizar

Uma aplicação não é feita apenas de operações que dão certo ou errado.

Ela possui etapas, condições e situações intermediárias que precisam ser consideradas.

Antes de pensar em qual componente criar ou qual método utilizar, vale perguntar:

Quais situações essa funcionalidade pode enfrentar e como minha aplicação deve reagir a cada uma delas?

Muitas vezes, uma boa solução começa muito antes da primeira linha de código.

Projetos

Precisa desenvolver ou melhorar uma aplicação?

Conheça meus projetos ou entre em contato para conversar sobre sua necessidade.