Esperar sem travar: assíncrono e APIs

Promises, async/await e fetch: buscar dados de uma API e mostrar carregamento, sucesso, lista vazia e erro.

Cerca de 18 min · Revisado em

Ao final, você vai conseguir

  • Explicar por que algumas operações são assíncronas
  • Usar async/await com try/catch
  • Buscar JSON com fetch e verificar response.ok
  • Projetar os quatro estados de uma tela que depende de dados

Quase todo aplicativo que você usa mostra dados que estão em outro computador: o cardápio do restaurante, o saldo do banco, o endereço de um CEP. Buscar esses dados leva tempo, às vezes alguns segundos, e às vezes dá errado. Nesta aula você aprende a pedir dados sem travar a página e a mostrar para a pessoa, com honestidade, o que está acontecendo.

Esperar sem ficar parado

O JavaScript da página faz uma coisa de cada vez. Se ele ficasse parado esperando o servidor responder, nada mais funcionaria: nem clique, nem rolagem, nem animação. A página congelaria.

Síncrono
Cada linha termina antes da próxima começar. Somar dois números ou trocar um textContent é síncrono: acontece na hora.
Assíncrono
A operação começa agora e termina depois. O código segue em frente e uma função é chamada quando o resultado fica pronto. Pedidos pela rede, temporizadores e leitura de arquivos funcionam assim.

Quais destas operações demoram um tempo imprevisível e por isso são assíncronas?

Síncrona: acontece na hora · Assíncrona: termina depois

  • Somar o total do carrinho
  • Buscar o endereço de um CEP numa API
  • Trocar o texto de um botão
  • Esperar 3 segundos para esconder um aviso
  • Filtrar um array de produtos
  • Carregar a lista de pedidos do servidor

O primeiro assíncrono: setTimeout

setTimeout(funcao, milissegundos) pede ao navegador: “daqui a tanto tempo, chame esta função”. O navegador cuida do relógio, e o seu código continua rodando. É o jeito mais simples de ver o assíncrono acontecer.

Siga a ordem real de execução. Repare que o tempo zero não fura a fila.

console.log('Pedido feito');

setTimeout(() => {
  console.log('Pizza chegou');
}, 0);

console.log('Arrumando a mesa');
  1. Linha 1: Código síncrono: roda na hora. Saída: Pedido feito
  2. Linha 3: Agenda a função para depois. Mesmo com 0 milissegundos, ela entra na fila e espera a sua vez.
  3. Linha 7: O código continua, sem esperar o temporizador. Saída: Arrumando a mesa
  4. Linha 7: O script terminou. Agora o JavaScript está livre para atender a fila.
  5. Linha 4: A função agendada finalmente roda. Saída: Pizza chegou

Teste a ordem você mesmo

Antes de olhar o console, escreva num papel a ordem em que as quatro mensagens vão aparecer. Depois mude os tempos e veja o que acontece.

console.log('1. Peguei a senha');

setTimeout(() => {
  console.log('2. Fui chamado no caixa');
}, 1000);

setTimeout(() => {
  console.log('3. Recebi um SMS');
}, 0);

console.log('4. Sentei para esperar');

Em que ordem as mensagens aparecem no console?

setTimeout(() => console.log('A'), 500);
console.log('B');
setTimeout(() => console.log('C'), 0);
console.log('D');
  • B, D, C, A
  • A, B, C, D
  • B, C, D, A
  • B, D, A, C

Promises e async/await

pending

Pendente

A operação ainda está em andamento. Ainda não há valor nem erro. É quando a tela mostra “carregando”.

fulfilled

Cumprida

Deu certo e o valor chegou: a lista de produtos, o endereço do CEP. Uma Promise cumprida não muda mais.

rejected

Rejeitada

Deu errado: sem internet, servidor fora do ar. Em vez de valor, há um erro explicando o motivo.

Existem duas formas de usar uma Promise. A mais antiga encadeia funções com .then (então) e .catch (capturar). A mais nova, async/await, deixa o código com cara de passo a passo, e é a que você vai usar no dia a dia.

A mesma busca escrita das duas formas.

async/await

async function mostrarCardapio() {
  try {
    const pratos = await buscarCardapio();
    console.log(pratos);
  } catch (erro) {
    console.log('Falhou:', erro.message);
  }
}

.then e .catch

function mostrarCardapio() {
  buscarCardapio()
    .then((pratos) => {
      console.log(pratos);
    })
    .catch((erro) => {
      console.log('Falhou:', erro.message);
    });
}

As peças de uma função assíncrona.

async function carregar() {
  try {
    const produtos = await buscarProdutos();
    mostrar(produtos);
  } catch (erro) {
    mostrarErro(erro.message);
  } finally {
    esconderCarregando();
  }
}
  • async: Marca a função como assíncrona. Só dentro dela você pode usar await. Ela sempre devolve uma Promise.
  • try: “Tente”: o bloco onde fica o caminho feliz. Se qualquer linha dentro dele falhar, o JavaScript pula direto para o catch.
  • await: “Aguarde”: pausa só esta função até a Promise terminar e entrega o valor. O resto da página continua funcionando enquanto isso.
  • catch: “Capture”: roda quando a Promise é rejeitada ou alguma linha do try quebra. erro.message traz a explicação.
  • finally: “Por fim”: roda nos dois casos, sucesso ou erro. Ótimo para esconder o “carregando” ou reativar um botão.

O que aparece no console?

async function buscar() {
  const pratos = buscarCardapio(); // faltou algo aqui
  console.log(pratos);
}

buscar();
  • Promise {<pending>}
  • A lista de pratos
  • Um erro dizendo que faltou await
  • undefined

Complete a função para esperar o CEP, mostrar a cidade e avisar se der errado.

____ function mostrarCidade() {
  ____ {
    const endereco = ____ buscarCep();
    console.log(endereco.cidade);
  } ____ (erro) {
    console.log('Não foi possível buscar o CEP');
  }
}

Buscar dados de verdade com fetch

Uma API é um endereço na web que responde com dados em vez de páginas, normalmente em JSON, o formato que você viu na aula de objetos. Para pedir esses dados, o navegador oferece a função fetch (buscar), que devolve uma Promise.

O formato que você vai repetir em todo projeto.

async function buscarEndereco(cep) {
  const resposta = await fetch('https://viacep.com.br/ws/' + cep + '/json/');

  if (!resposta.ok) {
    throw new Error('Erro ' + resposta.status);
  }

  const endereco = await resposta.json();
  return endereco;
}
await fetch(url)
Faz a requisição e espera a resposta chegar. O resultado é um objeto com o status e o corpo, ainda não lido.
resposta.ok
true quando o status é da família 2xx. Com 404 ou 500, vale false.
throw new Error(...)
“Lance um erro”: interrompe a função e manda o erro para o catch de quem a chamou.
await resposta.json()
Lê o corpo e transforma o texto JSON em objetos e arrays. Também é assíncrono, por isso leva await.

Uma busca bem-sucedida e uma que falha

  1. Seu código → Navegador: fetch('/produtos'). Seu código pede os dados e recebe na hora uma Promise pendente. A página continua respondendo a cliques.
  2. Navegador → Servidor: GET /produtos. O navegador monta a requisição HTTP e envia ao servidor, exatamente como você viu na aula sobre a web.
  3. Servidor → Navegador: 200 OK + JSON. O servidor responde com status 200 e o corpo em JSON.
  4. Navegador → Seu código: resposta.ok === true. A Promise se cumpre. Seu código confere resposta.ok, lê o corpo com await resposta.json() e desenha a lista.
  5. Seu código → Servidor: GET /produtos/999. Agora, um pedido por um produto que não existe.
  6. Servidor → Seu código: 404 Not Found. O servidor respondeu, só que com um erro. O fetch cumpre a Promise mesmo assim: houve resposta. Cabe ao seu código ver que resposta.ok é false e lançar o erro.
  7. Seu código → Seu código: catch mostra o erro. O throw leva a execução para o catch, que mostra uma mensagem amigável na tela.

A API respondeu 404 Not Found. O que acontece com a Promise do fetch?

  • Ela é cumprida; você precisa conferir resposta.ok
  • Ela é rejeitada e o código pula para o catch
  • Ela fica pendente para sempre

Coloque em ordem o que uma função de busca faz.

  • Mostrar a mensagem de carregando
  • Esperar a resposta com await fetch(url)
  • Conferir resposta.ok e lançar um erro se for falso
  • Ler o corpo com await resposta.json()
  • Desenhar os dados na tela

Os quatro estados de uma tela com dados

Uma tela que depende de dados nunca tem só um jeito de aparecer. Quem projeta pensando apenas no caminho feliz entrega uma página que fica em branco quando a rede está lenta e quebra quando a API cai.

1

Carregando

O pedido saiu e a resposta não chegou. Mostre que algo está acontecendo, para a pessoa não achar que travou.

  • Texto “Carregando...” ou um esqueleto da lista
  • Use role="status" para leitores de tela

2

Sucesso

Os dados chegaram e há itens. Esconda o carregando e desenhe a lista.

3

Vazio

Deu certo, mas a lista veio vazia. Isso não é erro: explique e, se puder, sugira o que fazer.

  • “Nenhum pedido ainda. Que tal explorar o cardápio?”

4

Erro

Algo falhou. Diga em linguagem simples o que aconteceu e ofereça um caminho, como tentar de novo.

  • Nada de mostrar “Error 500” cru para a pessoa

Cardápio com os quatro estados

A função buscarProdutos é uma API de mentira: espera 800 ms e responde. Complete carregar para mostrar “Carregando...”, depois os produtos, uma mensagem com “Nenhum produto” se a lista vier vazia, e “Não foi possível carregar. Tente de novo.” se falhar. Troque falhar e vazio para true para ver cada estado na prévia.

<h2>Cardápio do dia</h2>
<p id="estado" role="status"></p>
<ul id="produtos"></ul>
body { font-family: system-ui, sans-serif; padding: 16px; }
#estado { color: #555; font-style: italic; }
li { padding: 6px 0; border-bottom: 1px solid #eee; }
// API de mentira: funciona como um fetch que já leu o JSON.
const falhar = false; // troque para true para simular uma falha
const vazio = false;  // troque para true para simular uma lista vazia

function buscarProdutos() {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (falhar) {
        reject(new Error('Servidor indisponível'));
      } else if (vazio) {
        resolve([]);
      } else {
        resolve([
          { nome: 'Coxinha', preco: 6.5 },
          { nome: 'Pão de queijo', preco: 4 },
          { nome: 'Pastel', preco: 8 },
        ]);
      }
    }, 800);
  });
}

const textoEstado = document.querySelector('#estado');
const lista = document.querySelector('#produtos');

function mostrarProdutos(produtos) {
  for (const produto of produtos) {
    const item = document.createElement('li');
    item.textContent = produto.nome + ': R$ ' + produto.preco.toFixed(2);
    lista.append(item);
  }
}

async function carregar() {
  // 1. mostre 'Carregando...' em textoEstado
  // 2. dentro de um try, espere (await) buscarProdutos()
  // 3. se a lista vier vazia, mostre 'Nenhum produto por enquanto.'
  //    se não, limpe textoEstado e chame mostrarProdutos
  // 4. no catch, mostre 'Não foi possível carregar. Tente de novo.'
}

carregar();
  • Mostra “Carregando” enquanto espera a resposta
  • Quando a resposta chega, mostra os 3 produtos
  • Usa try e catch para tratar a falha
  • Mostra a mensagem certa quando a API falha e quando a lista vem vazia

Qual estado da tela cada situação representa?

Carregando · Sucesso · Vazio · Erro

  • O pedido saiu há meio segundo e nada voltou
  • A API devolveu 12 pedidos
  • A busca por “sushi vegano” devolveu []
  • A pessoa está sem internet no metrô
  • A API respondeu 500 Internal Server Error
  • Uma pessoa nova abre a tela de favoritos

Investigar quando a busca falha

Com uma API real, o painel Network (Rede) das ferramentas de desenvolvimento vira seu melhor amigo. Cada fetch aparece como uma linha, com URL, status e o JSON que voltou na aba Response.

  • Status 404: confira a URL que você montou. Um espaço ou uma barra a mais muda tudo.
  • Status 500: o pedido pode estar certo; o problema está no servidor. Mostre o estado de erro.
  • Linha vermelha sem status, com aviso de CORS no console: o servidor não autorizou seu site a ler a resposta. O guia CORS sem mistério explica por que isso se resolve no servidor, não no seu código.
  • Tudo 200, mas a tela mostra undefined: abra a aba Response e confira os nomes dos campos. Talvez seja price, e não preco.

A lista aparece com “undefined: R$ NaN” em cada item. O Network mostra status 200. O que investigar primeiro?

  • Os nomes dos campos no JSON da resposta
  • Se o servidor está fora do ar
  • Se faltou o try/catch

Fechamento

  • Operações que dependem da rede ou do relógio são assíncronas: começam agora, terminam depois, e a página não trava enquanto isso.
  • Uma Promise começa pendente e termina cumprida (com valor) ou rejeitada (com erro); await espera esse fim dentro de uma função async.
  • try/catch separa o caminho feliz do tratamento de erro; finally roda nos dois casos.
  • O fetch só rejeita sem resposta: confira resposta.ok antes de ler com await resposta.json().
  • Toda tela com dados precisa de quatro estados: carregando, sucesso, vazio e erro.

Busque dados de uma API pública

Continue o projeto Aplicação com API da trilha. Desta vez os dados vêm de um servidor de verdade, e a sua tela precisa lidar com tudo o que pode acontecer no caminho.

  1. Escolha uma API pública e gratuita, como a ViaCEP (https://viacep.com.br/ws/01001000/json/) ou a BrasilAPI (https://brasilapi.com.br/api/cep/v1/01001000)
  2. Escreva uma função async com fetch, conferência de resposta.ok e try/catch
  3. Mostre os quatro estados na tela: carregando, sucesso, vazio e erro, com um botão de tentar de novo
  4. Force um erro digitando um CEP inválido e confira como a tela reage
  5. Abra o painel Network, encontre a requisição e anote URL, status e um campo do JSON
  6. Simule internet lenta no Network (opção Slow 4G) e veja se o carregando aparece

Referências

Cursos relacionados