Promises, async/await e fetch em JavaScript

Promises, async/await e fetch em JavaScript: 15 exemplos executáveis | We.Inc

Promises, async/await e a API fetch com uma linha do tempo do event loop passo a passo e 15 exemplos que você pode editar e executar: JSON, formulários, erros, requisições em paralelo, AbortController e retry.

Promises, async/await e fetch em JavaScript

Uma promise representa um resultado que chega mais tarde. Funções async retornam promises, e await pausa essa função até que uma delas seja resolvida. fetch(url) retorna uma promise de um Response: verifique response.ok e depois faça await response.json(). Envolva os awaits em try e catch, use Promise.all para requisições em paralelo e AbortController para cancelar.

O padrão de que a maioria das páginas precisa

Etapa
Código

Requisição
const res = await fetch(url)

Verificar o status
if (!res.ok) throw new Error(res.status)

Ler o corpo
const data = await res.json()

Tratar a falha
try { ... } catch (err) { ... }

Comece pela linha do tempo para ver por que o código depois de um await pode rodar antes dele. Depois edite qualquer exemplo e ele roda de novo na hora. As requisições aqui usam URLs data: ou servidores simulados, então nada sai do seu navegador.

Avance pela linha do tempo para ver a call stack e as duas filas.
Rode o exemplo 1 e tente prever a ordem antes de olhar.
Trabalhe com fetch, erros e verificação de status nos exemplos 5 a 8.
Compare o tempo sequencial e o paralelo no exemplo 9.
Copie os helpers de cancelamento, timeout e retry para o seu próprio código.

Nunca deixe uma promise sem um catch em algum ponto acima na cadeia; rejeições não tratadas escondem bugs reais.
Inicie as requisições independentes antes de fazer await em qualquer uma delas, e depois faça await de Promise.all.
Verifique res.ok em todo fetch. Uma página 404 lida como JSON lança um erro de sintaxe confuso.
Evite await dentro de forEach; ele não espera. Use for...of para sequência ou map com Promise.all para paralelo.
Aborte as requisições no cleanup dos effects do React para que uma resposta lenta não atualize um componente que já saiu da tela.

Perguntas frequentes

Qual a diferença entre promises e async/await?

Nenhuma no que eles conseguem fazer: async/await é construído em cima de promises. Uma função async sempre retorna uma promise, e await desembrulha uma. O código fica parecido com código normal passo a passo, o que facilita tratar erros com try e catch.

Por que o fetch não lança erro em um 404?

O fetch trata qualquer resposta HTTP como uma requisição bem-sucedida, porque o servidor respondeu. Ele só rejeita em falhas de rede ou em uma requisição cancelada. Verifique você mesmo response.ok ou response.status.

Por que setTimeout com 0 roda depois de uma promise resolvida?

Os callbacks de promise vão para a fila de microtasks, que é esvaziada por completo depois do script atual. Um callback de timer é uma task, que espera a próxima volta do event loop.

Como cancelo uma requisição fetch?

Crie um AbortController, passe controller.signal nas opções do fetch e chame controller.abort(). A promise do fetch é rejeitada com um erro chamado AbortError.

Posso usar await no nível superior?

Sim, dentro de módulos JavaScript (script type="module" ou qualquer ES module empacotado). Em scripts clássicos, envolva o código em uma função async.

Erros que você vai ver

"Unexpected token < in JSON" significa que o servidor enviou HTML, geralmente uma página de erro, e o .json() tentou interpretá-lo. Verifique antes res.ok e o Content-Type.
"Failed to fetch" ou um TypeError é uma falha de rede ou de CORS. O navegador esconde os detalhes de propósito; abra a aba Network para ver se a requisição foi bloqueada.
Uma requisição que funciona em uma ferramenta mas não no navegador muitas vezes está sem os cabeçalhos CORS no servidor. Isso precisa ser corrigido no servidor, não no fetch.

Usando isso em um site real

Um formulário de contato envia seu FormData para um endpoint de formulário, mostra um estado de envio e troca para uma mensagem de agradecimento só quando res.ok é true. Mantenha o formulário HTML simples funcionando sem JavaScript como alternativa.
Em páginas que leem dados ao carregar, mostre um skeleton ou uma mensagem curta durante a espera, e um erro com botão de tentar de novo se falhar, em vez de uma caixa vazia.

Promises e async/await

1. O que roda quando

As linhas síncronas rodam primeiro, depois todos os callbacks de promise na fila (microtasks) e por fim o timer (uma task). Mude a ordem e rode de novo.

2. Criando uma promise

Uma promise é resolvida uma única vez: resolve entrega um valor, reject entrega um erro. then e catch rodam depois, nunca na hora.

3. A mesma coisa com async e await

await pausa só a função async em que está. A linha depois da chamada a main() roda antes de main terminar.

4. Erros com try, catch e finally

Dentro de uma função async, um await rejeitado lança um erro, então try e catch comuns funcionam. finally é o lugar para esconder um indicador de carregamento.

fetch para tarefas reais de sites

5. Carregar JSON com fetch

fetch retorna um Response; .json() lê e interpreta o corpo, o que é um segundo await. Este usa uma URL data: para funcionar offline.

6. Para o fetch, um 404 não é erro

O fetch só rejeita quando a requisição nem consegue ser feita (offline, bloqueada, URL inválida). Um 404 ou 500 resolve normalmente com ok igual a false, então verifique sempre.

7. Enviar um formulário com fetch

FormData lê todos os campos com nome. Aqui a requisição é montada mas não enviada, e o corpo é exibido para você ver exatamente o que um servidor receberia.

8. POST de JSON

Envie JSON convertendo-o em string e definindo você mesmo o cabeçalho Content-Type; o fetch não faz nenhum dos dois para objetos simples.

Várias requisições ao mesmo tempo

Qual helper de promise usar

Helper
Resolve quando
Use para

Promise.all
Todas são cumpridas, ou a primeira é rejeitada
Dados dos quais você precisa de cada parte

Promise.allSettled
Todas as promises foram resolvidas
Widgets independentes; informe cada resultado

Promise.race
A primeira é resolvida, de um jeito ou de outro
Disputar um timer contra uma requisição

Promise.any
A primeira é cumprida (rejeita só se todas rejeitarem)
Tentar espelhos; pegar o sucesso mais rápido

9. Sequencial versus paralelo

Fazer await de uma chamada por vez soma as esperas. Iniciar todas e fazer await de Promise.all espera só o tempo da mais lenta.

10. Promise.all versus Promise.allSettled

Promise.all rejeita assim que uma falha. allSettled espera todas e diz quais funcionaram, o que combina com dashboards de widgets independentes.

11. Muitas requisições, poucas por vez

Disparar centenas de requisições de uma vez pode estourar limites de taxa. Este pequeno pool mantém no máximo três em andamento.

Cancelar, timeout, retry

12. Cancelar com AbortController

Passe controller.signal para o fetch e chame abort() para interrompê-lo. A promise é rejeitada com um AbortError, que você geralmente ignora.

13. Desistir depois de um timeout

AbortSignal.timeout(ms) cria um sinal que aborta sozinho. Com fetch, o nome do erro é TimeoutError, então dá para diferenciá-lo de um cancelamento feito pelo usuário.

14. Retry com backoff

Tente de novo só os erros que podem passar, como um timeout ou um 503, e espere mais a cada vez para que um servidor sobrecarregado possa se recuperar.

15. Busca enquanto digita, sem resultados velhos

Espere uma pausa na digitação e aborte a requisição anterior quando uma nova começar, para que uma resposta antiga e lenta nunca sobrescreva uma mais nova.

Recebeu uma resposta que precisa ler? Cole no

formatador de JSON

O script inteiro é uma task. Ele começa na call stack.
A linha 1 roda na hora e imprime A.
setTimeout entrega o callback ao timer. Depois de 0 ms ele espera na fila de tasks.
A promise já está resolvida, então o callback dela vai direto para a fila de microtasks.
A linha 4 ainda é síncrona, então D é impresso antes de qualquer coisa na fila.
O script termina e a pilha fica vazia. Agora todas as microtasks rodam antes de qualquer task.
O callback da promise roda e imprime C.
As microtasks estão vazias, então o event loop pega a próxima task: o timer imprime B.

Linha do tempo do event loop

Call stack

Microtasks

Fila de tasks

Console

Etapa {i} de {n}.

Voltar

Próxima etapa

Pausar

Reproduzir

Reiniciar

Comece grátis · Sem cartão de crédito

Promises, async/await e fetch em JavaScript