Otimizando Chamadas de API no React: Estratégias de Debounce Explicadas

Ao construir aplicações React com campos de busca, recursos de autocompletar ou qualquer entrada que dispare chamadas de API, você rapidamente encontrará um problema comum: muitas requisições desnecessárias. Um usuário digitando “react framework” em uma caixa de busca pode gerar 14 chamadas de API separadas em apenas alguns segundos—uma para cada tecla pressionada. Isso não apenas desperdiça largura de banda, mas pode sobrecarregar seus servidores, degradar a performance e até mesmo incorrer em custos extras com APIs que cobram por requisição.

O debounce resolve esse problema ao atrasar a execução da função até depois de uma pausa especificada nos eventos. Neste artigo, explicarei como o debounce funciona no React, mostrarei como implementá-lo corretamente e ajudarei você a evitar armadilhas comuns que podem quebrar sua implementação de debounce.

Entendendo o Problema: Por que o Debounce Importa

Considere este componente de busca aparentemente inocente:

function SearchComponent() {
  const [query, setQuery] = useState('');
  
  const handleSearch = (e) => {
    const value = e.target.value;
    setQuery(value);
    fetchSearchResults(value); // Chamada de API a cada tecla pressionada
  };
  
  return (
    <input 
      type="text" 
      value={query}
      onChange={handleSearch}
      placeholder="Search..." 
    />
  );
}

Cada tecla pressionada dispara uma chamada de API. Para um digitador rápido inserindo “react hooks”, são 11 requisições de API separadas em rápida sucessão, com apenas a última mostrando os resultados que o usuário realmente quer.

Isso cria vários problemas:

1. Recursos desperdiçados: A maioria dessas requisições fica imediatamente obsoleta
2. UX ruim: Resultados piscando conforme as respostas chegam fora de ordem
3. Sobrecarga do servidor: Especialmente problemático em escala
4. Limitação de taxa: APIs de terceiros podem limitar ou bloquear sua aplicação

O que é Debouncing?

Debouncing é uma técnica de programação que garante que uma função não execute até depois que uma certa quantidade de tempo tenha passado desde que foi invocada pela última vez. Para entradas, isso significa esperar até que o usuário tenha parado de digitar antes de fazer uma chamada de API.

Aqui está uma representação visual do que acontece:

Sem debouncing:

Teclas: r → re → rea → reac → react
Chamadas API: r → re → rea → reac → react (5 chamadas)

Com debouncing (300ms):

Teclas: r → re → rea → reac → react → [pausa de 300ms]
Chamadas API:                          react (1 chamada)

Implementação Básica de Debounce

Vamos implementar uma função de debounce simples:

function debounce(func, delay) {
  let timeoutId;
  
  return function(...args) {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(() => {
      func.apply(this, args);
    }, delay);
  };
}

Esta função:

1. Recebe uma função e tempo de atraso como parâmetros
2. Retorna uma nova função que envolve a original
3. Limpa qualquer timeout existente quando chamada
4. Define um novo timeout para executar a função original após o atraso

Implementando Debounce no React (A Forma Errada)

Muitos desenvolvedores tentam implementar debounce no React assim:

function SearchComponent() {
  const [query, setQuery] = useState('');
  
  const handleSearch = (e) => {
    const value = e.target.value;
    setQuery(value);
    
    // Isso parece certo, mas não é!
    const debouncedFetch = debounce(() => {
      fetchSearchResults(value);
    }, 300);
    
    debouncedFetch();
  };
  
  return (
    <input 
      type="text" 
      value={query}
      onChange={handleSearch}
      placeholder="Search..." 
    />
  );
}

O problema: Isso cria uma nova função de debounce a cada tecla pressionada, anulando completamente o propósito. Cada tecla cria seu próprio timeout isolado que não sabe sobre os anteriores.

Debounce no React Feito Corretamente

Existem três abordagens principais para implementar debouncing adequadamente no React:

1. Usando useCallback para Referências de Função Estáveis

function SearchComponent() {
  const [query, setQuery] = useState('');
  
  // Cria a função debounced uma vez
  const debouncedFetch = useCallback(
    debounce((value) => {
      fetchSearchResults(value);
    }, 300),
    [] // Array de dependências vazio significa que isso é criado apenas uma vez
  );
  
  const handleSearch = (e) => {
    const value = e.target.value;
    setQuery(value);
    debouncedFetch(value);
  };
  
  return (
    <input 
      type="text" 
      value={query}
      onChange={handleSearch}
      placeholder="Search..." 
    />
  );
}

2. Usando um Hook Customizado para Implementação Mais Limpa

Criar um hook customizado torna sua lógica de debounce reutilizável e mais limpa:

function useDebounce(callback, delay) {
  const timeoutRef = useRef(null);
  
  useEffect(() => {
    // Limpa o timeout quando o componente desmonta
    return () => {
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, []);
  
  const debouncedCallback = useCallback((...args) => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
    
    timeoutRef.current = setTimeout(() => {
      callback(...args);
    }, delay);
  }, [callback, delay]);
  
  return debouncedCallback;
}

Usando o hook:

function SearchComponent() {
  const [query, setQuery] = useState('');
  
  const fetchResults = useCallback((searchTerm) => {
    fetchSearchResults(searchTerm);
  }, []);
  
  const debouncedFetch = useDebounce(fetchResults, 300);
  
  const handleSearch = (e) => {
    const value = e.target.value;
    setQuery(value);
    debouncedFetch(value);
  };
  
  return (
    <input 
      type="text" 
      value={query}
      onChange={handleSearch}
      placeholder="Search..." 
    />
  );
}

3. Usando uma Biblioteca Estabelecida

Para aplicações de produção, considere usar uma biblioteca testada em batalha:

import { useDebouncedCallback } from 'use-debounce';

function SearchComponent() {
  const [query, setQuery] = useState('');
  
  const debouncedFetch = useDebouncedCallback(
    (value) => {
      fetchSearchResults(value);
    },
    300
  );
  
  const handleSearch = (e) => {
    const value = e.target.value;
    setQuery(value);
    debouncedFetch(value);
  };
  
  return (
    <input 
      type="text" 
      value={query}
      onChange={handleSearch}
      placeholder="Search..." 
    />
  );
}

Bibliotecas populares de debounce para React incluem:

• use-debounce
• lodash.debounce com useCallback
• react-use (inclui hook useDebounce)

Armadilhas Comuns com Debounce no React

1. Recriar a Função de Debounce na Renderização

O erro mais comum é criar um novo wrapper de debounce a cada renderização:

// ❌ Errado - cria nova função de debounce a cada renderização
const handleChange = (e) => {
  const value = e.target.value;
  debounce(() => fetchData(value), 300)();
};

2. Problemas de Closure com Acesso ao Estado

Quando sua função debounced precisa acessar o estado mais recente:

// ❌ Errado - capturará valores antigos do estado
const debouncedFetch = useCallback(
  debounce(() => {
    // Isso usará o valor de query de quando a função debounce foi criada
    fetchSearchResults(query);
  }, 300),
  [] // Array de dependências vazio significa que isso captura o valor inicial de query
);

// ✅ Certo - passe o valor como argumento
const debouncedFetch = useCallback(
  debounce((value) => {
    fetchSearchResults(value);
  }, 300),
  []
);

3. Não Limpar Timeouts

Falhar em limpar timeouts quando componentes desmontam pode causar vazamentos de memória:

// ✅ Certo - limpe na desmontagem
useEffect(() => {
  return () => {
    debouncedFetch.cancel(); // Se usando uma biblioteca com método cancel
    // ou limpe sua referência de timeout
  };
}, [debouncedFetch]);

Padrões Avançados de Debounce

Debouncing com Execução Imediata

Às vezes você quer executar a função imediatamente na primeira chamada, então fazer debounce das chamadas subsequentes:

function useDebounceWithImmediate(callback, delay, immediate = false) {
  const timeoutRef = useRef(null);
  const isFirstCallRef = useRef(true);
  
  useEffect(() => {
    return () => {
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, []);
  
  return useCallback((...args) => {
    const callNow = immediate && isFirstCallRef.current;
    
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
    
    if (callNow) {
      callback(...args);
      isFirstCallRef.current = false;
    }
    
    timeoutRef.current = setTimeout(() => {
      if (!callNow) callback(...args);
      isFirstCallRef.current = immediate;
    }, delay);
  }, [callback, delay, immediate]);
}

Debouncing com Estado de Carregamento

Para melhor UX, você pode querer mostrar um indicador de carregamento:

function SearchComponent() {
  const [query, setQuery] = useState('');
  const [isLoading, setIsLoading] = useState(false);
  const [results, setResults] = useState([]);
  
  const debouncedFetch = useDebouncedCallback(
    async (value) => {
      try {
        setIsLoading(true);
        const data = await fetchSearchResults(value);
        setResults(data);
      } finally {
        setIsLoading(false);
      }
    },
    300
  );
  
  const handleSearch = (e) => {
    const value = e.target.value;
    setQuery(value);
    if (value) {
      setIsLoading(true); // Mostra carregamento imediatamente
      debouncedFetch(value);
    } else {
      setResults([]);
      setIsLoading(false);
    }
  };
  
  return (
    <>
      <input 
        type="text" 
        value={query}
        onChange={handleSearch}
        placeholder="Search..." 
      />
      {isLoading && <div>Carregando...</div>}
      <ul>
        {results.map(item => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
    </>
  );
}

Perguntas Frequentes

Conclusão

Ao implementar debouncing adequado em suas aplicações React, você criará uma experiência de usuário mais eficiente e responsiva enquanto reduz a carga desnecessária do servidor e custos potenciais. Seja escolhendo criar sua própria implementação de debounce ou usar uma biblioteca estabelecida, a chave é garantir que sua função de debounce persista entre renderizações e lide adequadamente com a limpeza para prevenir vazamentos de memória.