Guia Completo da API Fetch do JavaScript: Conceitos Básicos, Exemplos, Tratamento de Erros e Segurança

By 佐川 直弘 | Naohiro Sagawa (運営者)

※記事内に広告を含みます。Amazonアソシエイトとして適格販売により収入を得ています。　

1. Introdução: O que é a Fetch API?

O JavaScript desempenha um papel crucial no desenvolvimento front‑end de aplicações web. Entre suas diversas funcionalidades, a Fetch API é uma ferramenta poderosa para realizar comunicação assíncrona com servidores. Neste artigo explicamos como usar a Fetch API de forma amigável para iniciantes e apresentamos seus recursos por meio de exemplos práticos.

Qual é o papel da Fetch API?

A Fetch API é uma interface moderna e padrão para lidar com requisições e respostas HTTP. No passado, o XMLHttpRequest era amplamente utilizado, mas a Fetch API oferece um design mais simples e intuitivo.

Diferenças entre Fetch API e XMLHttpRequest

As principais diferenças entre a Fetch API e o tradicional XMLHttpRequest são as seguintes.

Conforme mostrado acima, a Fetch API é amplamente adotada como uma ferramenta mais flexível e amigável ao desenvolvedor no desenvolvimento web moderno.

Casos de uso comuns da Fetch API

A Fetch API é comumente utilizada nos seguintes cenários.

1. Recuperação de dados: Obter informações de usuários ou dados de posts de APIs.
2. Envio de dados: Enviar dados de formulários ou JSON para um servidor.
3. Atualizações em tempo real: Receber dados dinâmicos de um servidor e atualizar o conteúdo da página.
4. Integração com APIs externas: Conectar-se a APIs de terceiros para ampliar a funcionalidade.

Por essas razões, a Fetch API tornou‑se uma parte essencial do desenvolvimento JavaScript moderno.

Resumo

Nesta seção explicamos o papel básico e as vantagens da Fetch API. Em comparação ao tradicional XMLHttpRequest, a Fetch API é mais intuitiva, mais fácil de usar e baseada em Promises, tornando o tratamento de erros mais simples. Na próxima seção, exploraremos o uso básico da Fetch API com exemplos de código concretos.

Ao continuar, você aprenderá como recuperar e manipular dados usando a Fetch API na prática.

2. Uso básico da Fetch API (com código de exemplo)

Nesta seção explicamos o uso básico da Fetch API por meio de exemplos de código concretos. Mesmo iniciantes podem acompanhar, começando com uma requisição GET simples.

Sintaxe básica da Fetch API

A sintaxe básica da Fetch API é mostrada abaixo.

fetch(url, options)
  .then(response => {
    // Handle the response
  })
  .catch(error => {
    // Handle errors
  });

• url: Especifica a URL da requisição.
• options: Usado para configurar métodos HTTP e cabeçalhos (opcional).
• then: Lida com a resposta.
• catch: Lida com erros.

Exemplo de uma requisição GET

A seguir, um exemplo básico de uma requisição GET.

fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    if (!response.ok) {
      throw new Error('A network error occurred');
    }
    return response.json();
  })
  .then(data => {
    console.log(data); // Display data
  })
  .catch(error => {
    console.error('Error:', error);
  });

Usando async/await

Com o JavaScript moderno, você pode escrever um código mais limpo usando async/await.

async function fetchPost() {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/posts/1');
    if (!response.ok) {
      throw new Error('A network error occurred');
    }
    const data = await response.json();
    console.log(data); // Display data
  } catch (error) {
    console.error('Error:', error);
  }
}

fetchPost();

Adicionando parâmetros de URL

Para incluir parâmetros de consulta, escreva a requisição da seguinte forma.

const userId = 1;
fetch(`https://jsonplaceholder.typicode.com/posts?userId=${userId}`)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Resumo

Nesta seção abordamos os fundamentos de como fazer requisições GET usando a Fetch API.

• Sintaxe básica: Design simples e fácil de entender.
• Tratamento de erros: Suporta erros de rede e HTTP.
• async/await: Melhora a legibilidade e a manutenção.
• Parâmetros de URL: Implementa facilmente condições dinâmicas.

A próxima seção explica como processar os dados de resposta retornados pela Fetch API em mais detalhes.

3. Manipulação de Resposta e Conversão de Formato de Dados

Nesta seção, explicamos como lidar com respostas obtidas usando a Fetch API. Focamos especialmente na conversão de dados JSON e no trabalho com dados de texto e binários.

O que é o Objeto de Resposta da Fetch API?

Com a Fetch API, a resposta retornada após uma requisição é fornecida como um objeto Response.

Principais Propriedades

Obtendo e Convertendo Dados JSON

Com a Fetch API, os servidores costumam retornar dados no formato JSON.

fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    if (!response.ok) {
      throw new Error('Response error: ' + response.status);
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Obtendo Dados de Texto

Em alguns casos, pode ser necessário obter dados em texto simples em vez de JSON.

fetch('https://example.com/textfile.txt')
  .then(response => response.text())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Obtendo Dados Binários

Para obter imagens ou arquivos como dados binários, use blob() ou arrayBuffer().

fetch('https://example.com/image.jpg')
  .then(response => response.blob())
  .then(blob => {
    const url = URL.createObjectURL(blob);
    document.getElementById('image').src = url;
  })
  .catch(error => console.error('Error:', error));

Resumo

Nesta seção, você aprendeu como lidar com respostas da Fetch API e converter formatos de dados.

• Dados JSON: Suporta o formato de resposta de servidor mais comum.
• Dados de texto e binários: Recupera diferentes formatos conforme necessário.
• Cabeçalhos de resposta: Úteis para gerenciamento de dados e verificações de segurança.

4. Enviando Requisições POST (Com Exemplos Práticos)

Nesta seção, explicamos como enviar dados a um servidor usando requisições POST com a Fetch API. Abordamos como enviar dados de formulário e dados JSON usando exemplos práticos.

Sintaxe Básica para uma Requisição POST

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})

• method: Especifica o método HTTP a ser usado (neste caso, POST).
• headers: Especifica o formato dos dados (por exemplo, JSON ou dados de formulário).
• body: Converte os dados para uma string e os envia.

Exemplo: Enviando Dados JSON

const userData = {
  name: 'Taro Tanaka',
  email: 'taro.tanaka@example.com'
};

fetch('https://jsonplaceholder.typicode.com/posts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(userData)
})
  .then(response => response.json())
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Error:', error));

Exemplo: Enviando Dados de Formulário

const formData = new FormData();
formData.append('name', 'Taro Tanaka');
formData.append('email', 'taro.tanaka@example.com');

fetch('https://example.com/api/submit', {
  method: 'POST',
  body: formData
})
  .then(response => response.text())
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Error:', error));

Exemplo: Requisição com Autenticação

fetch('https://example.com/api/protected', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({ query: 'data' })
})
  .then(response => response.json())
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Error:', error));

Resumo

Nesta seção, abordamos os conceitos básicos e o uso prático de requisições POST com a Fetch API.

• Envio de dados JSON: Ideal para integração de APIs.
• Envio de dados de formulário: Funciona bem para formulários simples e upload de arquivos.
• Requisições autenticadas: Suporta requisitos de segurança de APIs.

A próxima seção aprofunda o tratamento de erros e técnicas de depuração da Fetch API.

5. Técnicas de Tratamento de Erros e Depuração

Nesta seção, analisamos detalhadamente as técnicas de tratamento de erros e depuração ao usar a Fetch API.

Erros Comuns que Ocorrrem com a Fetch API

Tratamento Básico de Erros

fetch('https://jsonplaceholder.typicode.com/posts/9999')
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error: ${response.status}`);
    }
    return response.json();
  })
  .catch(error => console.error('Error:', error.message));

Tratamento de Timeouts

const controller = new AbortController();
const signal = controller.signal;

const timeout = setTimeout(() => controller.abort(), 5000);

fetch('https://jsonplaceholder.typicode.com/posts', { signal })
  .then(response => response.json())
  .catch(error => {
    if (error.name === 'AbortError') {
      console.error('Timeout: The request was aborted');
    } else {
      console.error('Error:', error.message);
    }
  })
  .finally(() => clearTimeout(timeout));

Técnicas de Depuração

1. Saída de logs:

   fetch('https://example.com/api/data')
     .then(response => {
       console.log('Status code:', response.status);
       return response.json();
     })
     .then(data => console.log('Data:', data))
     .catch(error => console.error('Error:', error.message));
   

2. Ferramentas de desenvolvedor do navegador (aba Network):

• Inspecione requisições e respostas em tempo real.

Resumo

Nesta seção, exploramos técnicas de tratamento de erros e depuração para a Fetch API.

• Erros comuns: Erros de rede, erros de análise de JSON e problemas de timeout.
• Tratamento detalhado de erros: Exemplos práticos com lógica de tratamento de erros clara.
• Depuração: Identifique problemas usando logs e as ferramentas de desenvolvedor do navegador.

A próxima seção explica padrões avançados de uso e medidas de segurança para a Fetch API.

6. Uso Avançado e Medidas de Segurança

Nesta seção, explicamos técnicas avançadas de uso e considerações de segurança para a Fetch API.

Cancelamento de Requisições (AbortController)

const controller = new AbortController();
const signal = controller.signal;

fetch('https://jsonplaceholder.typicode.com/posts', { signal })
  .then(response => response.json())
  .catch(error => {
    if (error.name === 'AbortError') {
      console.error('The request was aborted');
    } else {
      console.error('Error:', error.message);
    }
  });

setTimeout(() => controller.abort(), 3000); // Abort after 3 seconds

Requisições com Credenciais de Autenticação

const token = 'YOUR_ACCESS_TOKEN';

fetch('https://example.com/api/protected', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log('Data:', data))
  .catch(error => console.error('Error:', error));

Suporte a CORS (Cross-Origin Resource Sharing)

fetch('https://example.com/api/data', {
  method: 'GET',
  mode: 'cors'
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Resumo

Nesta seção, abordamos o uso avançado da Fetch API e medidas de segurança.

• Cancelamento de requisições: Melhore a eficiência usando AbortController.
• Requisições autenticadas: Implemente tokens de API e contramedidas contra CSRF.
• Manipulação de CORS: Resolva problemas de origem cruzada através de configuração adequada.

7. Erros Comuns e Solução de Problemas (Com Tabela Resumo)

In this section, we explain common errors you may encounter when using the Fetch API and how to resolve them.

Erros Comuns e Suas Causas

Manipulação Detalhada de Erros

fetch('https://invalid-url.example.com')
  .then(response => response.json())
  .catch(error => {
    if (error.message.includes('Failed to fetch')) {
      console.error('Network error');
    } else {
      console.error('Other error:', error.message);
    }
  });

Resumo

Nesta seção, revisamos erros comuns da Fetch API e como lidar com eles.

• Erros típicos: Erros de rede, erros de formato JSON e problemas de tempo limite.
• Manipulação detalhada: Exemplos práticos demonstrando manipulação robusta de erros.

8. Exemplo Prático: Construindo um Aplicativo Web Simples Usando Dados de API

Nesta seção, explicamos como criar um aplicativo web simples que recupera dados de uma API externa usando a Fetch API.

Preparando o HTML

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <title>Fetch API Sample App</title>
</head>
<body>
  <h1>Post List</h1>
  <button id="fetchButton">Fetch Data</button>
  <ul id="postList"></ul>
  <p id="errorMessage" style="color: red;"></p>

  <script src="app.js"></script>
</body>
</html>

Criando o Código JavaScript

const fetchButton = document.getElementById('fetchButton');
const postList = document.getElementById('postList');
const errorMessage = document.getElementById('errorMessage');

async function fetchPosts() {
  fetchButton.disabled = true;
  errorMessage.textContent = '';
  postList.innerHTML = '';

  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/posts');
    if (!response.ok) {
      throw new Error(`HTTP error: ${response.status}`);
    }
    const posts = await response.json();
    posts.forEach(post => {
      const listItem = document.createElement('li');
      listItem.textContent = `${post.id}: ${post.title}`;
      postList.appendChild(listItem);
    });
  } catch (error) {
    errorMessage.textContent = 'Failed to retrieve data.';
  } finally {
    fetchButton.disabled = false;
  }
}

fetchButton.addEventListener('click', fetchPosts);

Resumo

Nesta seção, demonstramos como construir um aplicativo web prático usando a Fetch API.

• Recursos principais: Recuperação de dados e renderização de listas.
• Manipulação de erros: Exibição de mensagens amigáveis ao usuário em caso de falha.

9. Conclusão e Próximos Passos

Neste artigo, abordamos a Fetch API de forma abrangente, desde o básico até o uso avançado e exemplos práticos. Nesta seção final, revisamos os pontos principais de cada seção e sugerimos o que aprender a seguir.

Principais Conclusões

Estrutura Básica e Recursos da Fetch API

• A Fetch API é uma interface poderosa para realizar comunicação assíncrona com servidores em JavaScript.
• Comparada ao tradicional XMLHttpRequest, ela é mais simples, mais flexível e baseada em Promises, o que melhora muito a legibilidade.

Recuperação de Dados e Manipulação de Respostas

• Explicamos como recuperar dados JSON, texto e binários.
• Usando async/await, você pode escrever código mais intuitivo com manipulação de erros mais simples.

Envio de Dados e Requisições POST

• Você aprendeu como enviar dados JSON e dados de formulário para um servidor.
• Também foram abordadas requisições seguras usando tokens de autenticação.

Técnicas de Manipulação de Erros e Depuração

• Introduzimos soluções práticas para erros de rede e erros de análise de JSON.
• Técnicas avançadas como tempos limite de requisição e abortar requisições foram implementadas.

Construindo Aplicações Web Práticas

• Você construiu uma aplicação web que recupera dados de uma API externa e os exibe dinamicamente na interface.
• Através da manipulação de erros e controle de estado de botões, você aprendeu padrões de design que refletem cenários reais de desenvolvimento.

Próximos Passos

Para aproveitar ainda melhor a Fetch API, considere aprender os seguintes tópicos.

Técnicas Avançadas de Implementação de API

• Paginação e ordenação: Otimize o processamento ao lidar com grandes conjuntos de dados.
• Funcionalidade de busca: Implemente filtragem de dados com base na entrada do usuário.
• Envio de arquivos: Gerencie o upload de imagens e vídeos.

Melhoras de Segurança

• OAuth 2.0 e autenticação: Entenda os processos de autenticação e autorização para conexões de API seguras.
• Proteção contra CSRF e XSS: Implemente envios de formulário mais seguros e defenda-se contra scripts maliciosos.

Integração com Tecnologias Modernas

• Biblioteca Axios: Uma alternativa popular à Fetch API que simplifica o gerenciamento de requisições HTTP.
• GraphQL: Um modelo de design de API moderno que otimiza a recuperação de dados em comparação com APIs REST.
• Comunicação em tempo real: Implemente troca de dados em tempo real usando WebSocket ou Server‑Sent Events.

Recursos de Aprendizado

Use a documentação oficial e os recursos de aprendizado a seguir para aprimorar ainda mais suas habilidades.

• MDN Web Docs (Oficial): Documentação detalhada da Fetch API
• JSONPlaceholder (API de teste): Uma API dummy gratuita para testes
• Site de aprendizado de JavaScript: JavaScript.info

Notas Finais

Através deste artigo, você adquiriu conhecimento e habilidades práticas que cobrem tudo, desde o básico até o uso real da Fetch API.

A Fetch API é amplamente utilizada para tarefas que vão desde a simples recuperação de dados até integrações complexas de API. Ao aplicar o que aprendeu aqui em projetos reais, você pode ganhar ainda mais experiência prática.

Próximas ações:

• Crie pequenos projetos usando APIs reais para ganhar experiência prática.
• Fortaleça o tratamento de erros e as medidas de segurança para melhorar a prontidão para produção.
• Adote novas tecnologias como GraphQL e comunicação em tempo real para expandir ainda mais seu conjunto de habilidades.