O Guia Definitivo da API Fetch do Node: Fazendo Requisições HTTP no Node.js

As requisições HTTP são uma parte fundamental do desenvolvimento web moderno. Com a introdução da Fetch API no Node.js, os desenvolvedores agora têm uma forma poderosa e consistente de fazer requisições de rede em ambientes de navegador e servidor. Neste tutorial abrangente, exploraremos como usar o Node fetch de forma eficaz em seus projetos.

O que é a Node Fetch API e por que você deve usá-la?

A Node fetch API é um mecanismo moderno baseado em promessas para fazer requisições HTTP em aplicações Node.js. Originalmente uma feature exclusiva do navegador, o fetch se tornou uma funcionalidade experimental no Node.js v18 e atingiu a estabilidade no Node.js v21.

Principais benefícios de usar o Node Fetch:

Funcionalidade embutida: Sem necessidade de instalar pacotes de terceiros
Baseado em promessas: Sintaxe limpa e moderna com suporte a async/await
Familiaridade multiplataforma: Mesma API que o fetch do lado do navegador
Desempenho melhorado: Construído sobre o cliente HTTP de alto desempenho Undici

Testando suas requisições da Node Fetch API com ferramentas modernas

Ao aprender a usar o Node fetch, é essencial ter ferramentas confiáveis para testar seus endpoints da API. Apidog se destaca como a melhor alternativa ao Postman para testar e documentar suas requisições da Node fetch API.

Como uma plataforma de desenvolvimento de API tudo-em-um, Apidog combina documentação de API, testes e servidores fictícios em uma única interface intuitiva.

Ao desenvolver aplicações com o Node fetch, Apidog ajuda você a visualizar respostas, colaborar com membros da equipe e garantir que suas chamadas de API estejam funcionando corretamente antes de implementá-las no código. Sua capacidade de gerar trechos de código para requisições do Node fetch torna a transição do teste para a implementação sem esforço.

botão

Configurando seu ambiente para o Node Fetch

Pré-requisitos para usar o Node Fetch

Antes de mergulhar em exemplos de Node fetch, certifique-se de que você tem:

Node.js v18 ou superior (preferencialmente v21+ para suporte estável ao fetch)
Verifique a versão do seu Node.js:

node -v

Compatibilidade de versão do Node Fetch

Node.js v21+: Fetch é estável e pronto para uso em produção
Node.js v18-v20: Fetch está disponível, mas experimental (use a flag -experimental-fetch)
Versões mais antigas do Node.js: Instale o pacote node-fetch ou atualize o Node.js

Se você estiver usando v18-v20, execute suas aplicações com:

node --experimental-fetch app.js

Fazendo sua primeira requisição Node Fetch

Vamos começar com uma requisição básica GET usando o Node fetch:

// Requisição GET básica com Node fetch
fetch('<https://api.example.com/data>')
  .then(response => {
    if (!response.ok) {
      throw new Error(`Erro HTTP! Status: ${response.status}`);
    }
    return response.json(); // Parse da resposta JSON
  })
  .then(data => {
    console.log('Dados recebidos:', data);
  })
  .catch(error => {
    console.error('Erro no fetch:', error);
  });

Usando Node Fetch com Async/Await

Para um código mais limpo, você pode usar async/await com o Node fetch:

async function fetchData() {
  try {
    const response = await fetch('<https://api.example.com/data>');

    if (!response.ok) {
      throw new Error(`Erro HTTP! Status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Dados recebidos:', data);
    return data;
  } catch (error) {
    console.error('Erro no fetch:', error);
  }
}

// Chame a função
fetchData();

Métodos de requisição avançados do Node Fetch

Fazendo requisições POST com o Node Fetch

async function postData(url, data) {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      throw new Error(`Erro HTTP! Status: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Erro no fetch POST:', error);
  }
}

// Exemplo de uso
const newUser = {
  name: 'John Doe',
  email: 'john@example.com',
};

postData('<https://api.example.com/users>', newUser)
  .then(data => console.log('Usuário criado:', data));

Requisições PUT com o Node Fetch

async function updateData(url, data) {
  try {
    const response = await fetch(url, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      throw new Error(`Erro HTTP! Status: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Erro no fetch PUT:', error);
  }
}

// Exemplo de uso
const updatedUser = {
  id: 1,
  name: 'Jane Smith',
  email: 'jane@example.com',
};

updateData('<https://api.example.com/users/1>', updatedUser)
  .then(data => console.log('Usuário atualizado:', data));

Requisições DELETE com o Node Fetch

async function deleteResource(url) {
  try {
    const response = await fetch(url, {
      method: 'DELETE',
    });

    if (!response.ok) {
      throw new Error(`Erro HTTP! Status: ${response.status}`);
    }

    // Algumas APIs não retornam conteúdo ao deletar
    if (response.status === 204) {
      return { success: true };
    }

    return await response.json();
  } catch (error) {
    console.error('Erro no fetch DELETE:', error);
  }
}

// Exemplo de uso
deleteResource('<https://api.example.com/users/1>')
  .then(result => console.log('Resultado da exclusão:', result));

Tratando diferentes tipos de resposta com o Node Fetch

O Node fetch pode trabalhar com vários formatos de resposta:

Tratamento de resposta JSON

fetch('<https://api.example.com/data>')
  .then(response => response.json())
  .then(data => console.log(data));

Tratamento de resposta de texto

fetch('<https://example.com/plain-text>')
  .then(response => response.text())
  .then(text => console.log(text));

Tratamento de dados binários

fetch('<https://example.com/image.png>')
  .then(response => response.arrayBuffer())
  .then(buffer => {
    // Tratar dados binários
    const bytes = new Uint8Array(buffer);
    console.log('Tamanho dos dados binários:', bytes.length);
  });

Personalizando requisições do Node Fetch com cabeçalhos e opções

Definindo cabeçalhos personalizados

fetch('<https://api.example.com/protected-data>', {
  headers: {
    'Authorization': 'Bearer SEU_TOKEN_AQUI',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'User-Agent': 'Minha Aplicação Node.js'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Configurando opções de requisição

fetch('<https://api.example.com/data>', {
  method: 'GET',
  headers: { 'Content-Type': 'application/json' },
  cache: 'no-cache',
  redirect: 'follow',      // follow, error, ou manual
  referrerPolicy: 'no-referrer'
})
.then(response => response.json())
.then(data => console.log(data));

Tratamento de erros com o Node Fetch

Tratamento de erros abrangente

Um aspecto importante a entender sobre o Node fetch é que ele não rejeita em códigos de status de erro HTTP. A promessa só é rejeitada em erros de rede ou se algo impediu a requisição de ser concluída.

Aqui está uma abordagem abrangente para o tratamento de erros:

async function fetchWithErrorHandling(url) {
  try {
    const response = await fetch(url);

    // Verificação de erros HTTP
    if (!response.ok) {
      // Tente obter detalhes do erro da resposta
      let errorDetails;
      try {
        errorDetails = await response.json();
      } catch (e) {
        errorDetails = await response.text();
      }

      throw new Error(
        `Erro HTTP! Status: ${response.status}, Detalhes: ${
          typeof errorDetails === 'object'
            ? JSON.stringify(errorDetails)
            : errorDetails
        }`
      );
    }

    return await response.json();
  } catch (error) {
    // Erros de rede, erros de parsing e nossos erros HTTP personalizados
    console.error('Fetch falhou:', error.message);
    throw error; // Relançar para permitir que o código chamador trate
  }
}

Implementando timeout de requisição com o Node Fetch

O Node fetch não tem suporte a timeout embutido, mas você pode implementá-lo usando AbortController:

async function fetchWithTimeout(url, options = {}, timeoutMs = 5000) {
  const controller = new AbortController();
  const { signal } = controller;

  // Configurar timeout
  const timeout = setTimeout(() => {
    controller.abort();
  }, timeoutMs);

  try {
    const response = await fetch(url, { ...options, signal });
    clearTimeout(timeout); // Limpar timeout se o fetch for concluído

    if (!response.ok) {
      throw new Error(`Erro HTTP! Status: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    clearTimeout(timeout);
    if (error.name === 'AbortError') {
      throw new Error(`Requisição expirou após ${timeoutMs}ms`);
    }
    throw error;
  }
}

// Exemplo de uso
fetchWithTimeout('<https://api.example.com/data>', {}, 3000)
  .then(data => console.log(data))
  .catch(error => console.error('Erro:', error.message));

Tratando autenticação com o Node Fetch

Autenticação básica

const username = 'user';
const password = 'password';
const credentials = Buffer.from(`${username}:${password}`).toString('base64');

fetch('<https://api.example.com/protected>', {
  headers: {
    'Authorization': `Basic ${credentials}`
  }
})
.then(response => response.json())
.then(data => console.log(data));

Autenticação por Token Bearer

const token = 'seu_token_jwt_ou_oauth';

fetch('<https://api.example.com/protected>', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
.then(response => response.json())
.then(data => console.log(data));

Melhores práticas para usar o Node Fetch em produção

Sempre verificar o status da resposta: Não assuma que as respostas são bem-sucedidas
Tratar diferentes tipos de conteúdo de forma adequada: Use o método correto para seu tipo de resposta (json(), text(), etc.)
Implementar tratamento de erros adequado: Crie funções utilitárias que tratem erros de forma consistente
Definir timeouts de requisição: Evite requisições pendentes com AbortController
Criar wrappers reutilizáveis para fetch: Construa uma camada de serviço com padrões comuns de requisição
Considerar lógica de repetição para requisições com falha: Implemente backoff exponencial para APIs instáveis
Usar variáveis de ambiente para URLs base: Mantenha URLs específicas do ambiente fora do código

Solução de problemas comuns do Node Fetch

Erro "Fetch não está definido"

Se você encontrar ReferenceError: fetch is not defined, verifique:

Você está usando Node.js v18+
Para Node.js v18-v20, use a flag -experimental-fetch
Para versões mais antigas, instale o pacote node-fetch

Problemas de certificado HTTPS

O Node fetch herda o tratamento de certificados HTTPS do Node. Para certificados personalizados:

const https = require('https');
const fs = require('fs');

const httpsAgent = new https.Agent({
  ca: fs.readFileSync('./custom-certificate.pem')
});

fetch('<https://api.example.com/data>', {
  agent: httpsAgent
})
.then(response => response.json())
.then(data => console.log(data));

Conclusão: Adotando o Node Fetch em seus projetos

A Node fetch API representa uma melhoria significativa na forma como fazemos requisições HTTP em aplicações Node.js. Com sua interface baseada em promessas, comportamento consistente em várias plataformas e implementação nativa, está se tornando a escolha preferida para o desenvolvimento moderno em Node.js.

Ao dominar o Node fetch, você pode criar um código mais manutenível que aproveita os recursos modernos do JavaScript, enquanto desfruta de um desempenho melhorado em comparação com bibliotecas antigas de clientes HTTP. À medida que a implementação estável continua a amadurecer no Node.js, podemos esperar que ainda mais desenvolvedores adotem essa poderosa API como sua abordagem padrão para fazer requisições HTTP.

Agora que você tem uma compreensão abrangente do Node fetch, você está pronto para implementá-lo em seus próprios projetos e aproveitar esta poderosa API para todas as suas necessidades de requisições HTTP.

botão