node fetch
v3.3.2
Um módulo leve que traz API buscar o Node.JS.
Você pode estar procurando os documentos V2
Em vez de implementar XMLHttpRequest no Node.js para executar o Polyfill Fetch específico do navegador, por que não ir do http nativo para fetch diretamente a API? Portanto, node-fetch , código mínimo para uma API compatível com window.fetch no Node.js Runtime.
Consulte Isomorphic-Unfetch de Jason Miller ou o cross-getch de Leonardo Quixada para o uso isomórfico (exportações node-fetch para o lado do servidor, whatwg-fetch para o lado do cliente).
window.fetch API.res.text() e res.json() ) para UTF-8 automaticamente.window.fetch oferece, fique à vontade para abrir um problema. A liberação estável atual ( 3.x ) requer pelo menos node.js 12.20.0.
npm install node-fetch import fetch from 'node-fetch' ; node-fetch da V3 é um módulo apenas para ESM-você não pode importá-lo com require() .
Se você não puder mudar para o ESM, use V2, que permanece compatível com o Commonjs. As correções críticas de bugs continuarão sendo publicadas para V2.
npm install node-fetch@2 Como alternativa, você pode usar a função Async import() do CommonJS para carregar node-fetch de forma assíncrona:
// mod.cjs
const fetch = ( ... args ) => import ( 'node-fetch' ) . then ( ( { default : fetch } ) => fetch ( ... args ) ) ; Para usar fetch() sem importá -lo, você pode corrigir o objeto global no nó:
// fetch-polyfill.js
import fetch , {
Blob ,
blobFrom ,
blobFromSync ,
File ,
fileFrom ,
fileFromSync ,
FormData ,
Headers ,
Request ,
Response ,
} from 'node-fetch'
if ( ! globalThis . fetch ) {
globalThis . fetch = fetch
globalThis . Headers = Headers
globalThis . Request = Request
globalThis . Response = Response
}
// index.js
import './fetch-polyfill'
// ... Usando uma versão antiga do Node-Fetch? Confira os seguintes arquivos:
Nota: A documentação abaixo está atualizada com as versões 3.x , se você estiver usando uma versão mais antiga, verifique como atualizar.
import fetch from 'node-fetch' ;
const response = await fetch ( 'https://github.com/' ) ;
const body = await response . text ( ) ;
console . log ( body ) ; import fetch from 'node-fetch' ;
const response = await fetch ( 'https://api.github.com/users/github' ) ;
const data = await response . json ( ) ;
console . log ( data ) ; import fetch from 'node-fetch' ;
const response = await fetch ( 'https://httpbin.org/post' , { method : 'POST' , body : 'a=1' } ) ;
const data = await response . json ( ) ;
console . log ( data ) ; import fetch from 'node-fetch' ;
const body = { a : 1 } ;
const response = await fetch ( 'https://httpbin.org/post' , {
method : 'post' ,
body : JSON . stringify ( body ) ,
headers : { 'Content-Type' : 'application/json' }
} ) ;
const data = await response . json ( ) ;
console . log ( data ) ; URLSearchParams está disponível no objeto global no Node.js a partir de v10.0.0. Consulte a documentação oficial para obter mais métodos de uso.
NOTA: O cabeçalho Content-Type é definido apenas automaticamente como x-www-form-urlencoded quando uma instância de URLSearchParams é dada como tal:
import fetch from 'node-fetch' ;
const params = new URLSearchParams ( ) ;
params . append ( 'a' , 1 ) ;
const response = await fetch ( 'https://httpbin.org/post' , { method : 'POST' , body : params } ) ;
const data = await response . json ( ) ;
console . log ( data ) ; Nota: as respostas 3xx-5xx não são exceções e devem ser tratadas em then() , consulte a próxima seção.
Envolver a função de busca em um bloco try/catch , captura todas as exceções, como erros originários das bibliotecas do Node Core, como erros de rede e erros operacionais, que são instâncias do FetchError. Consulte o documento de manuseio de erros para obter mais detalhes.
import fetch from 'node-fetch' ;
try {
await fetch ( 'https://domain.invalid/' ) ;
} catch ( error ) {
console . log ( error ) ;
}É comum criar uma função auxiliar para verificar se a resposta não contém respostas de erro ao cliente (4xx) ou servidor (5xx):
import fetch from 'node-fetch' ;
class HTTPResponseError extends Error {
constructor ( response ) {
super ( `HTTP Error Response: ${ response . status } ${ response . statusText } ` ) ;
this . response = response ;
}
}
const checkStatus = response => {
if ( response . ok ) {
// response.status >= 200 && response.status < 300
return response ;
} else {
throw new HTTPResponseError ( response ) ;
}
}
const response = await fetch ( 'https://httpbin.org/status/400' ) ;
try {
checkStatus ( response ) ;
} catch ( error ) {
console . error ( error ) ;
const errorBody = await error . response . text ( ) ;
console . error ( `Error body: ${ errorBody } ` ) ;
}Os cookies não são armazenados por padrão. No entanto, os cookies podem ser extraídos e passados manipulando os cabeçalhos de solicitação e resposta. Consulte o cabeçalho do extrato de defesa do conjunto para obter detalhes.
O "Node.js Way" é usar fluxos quando possível. Você pode transportar res.body para outro fluxo. Este exemplo usa o stream.pipline para anexar manipuladores de erros de fluxo e aguardar o download concluído.
import { createWriteStream } from 'node:fs' ;
import { pipeline } from 'node:stream' ;
import { promisify } from 'node:util'
import fetch from 'node-fetch' ;
const streamPipeline = promisify ( pipeline ) ;
const response = await fetch ( 'https://github.githubassets.com/images/modules/logos_page/Octocat.png' ) ;
if ( ! response . ok ) throw new Error ( `unexpected response ${ response . statusText } ` ) ;
await streamPipeline ( response . body , createWriteStream ( './octocat.png' ) ) ; No Node.js 14, você também pode usar iteradores assíncronos para ler body ; No entanto, tenha cuidado para capturar erros - quanto mais uma resposta é executada, maior a probabilidade de encontrar um erro.
import fetch from 'node-fetch' ;
const response = await fetch ( 'https://httpbin.org/stream/3' ) ;
try {
for await ( const chunk of response . body ) {
console . dir ( JSON . parse ( chunk . toString ( ) ) ) ;
}
} catch ( err ) {
console . error ( err . stack ) ;
} No Node.js 12, você também pode usar iteradores assíncronos para ler body ; No entanto, os iteradores assíncronos com fluxos não amadureceram até o Node.js 14, portanto, você precisa fazer algum trabalho extra para garantir que você lide com erros diretamente do fluxo e aguarde a resposta para fechar completamente.
import fetch from 'node-fetch' ;
const read = async body => {
let error ;
body . on ( 'error' , err => {
error = err ;
} ) ;
for await ( const chunk of body ) {
console . dir ( JSON . parse ( chunk . toString ( ) ) ) ;
}
return new Promise ( ( resolve , reject ) => {
body . on ( 'close' , ( ) => {
error ? reject ( error ) : resolve ( ) ;
} ) ;
} ) ;
} ;
try {
const response = await fetch ( 'https://httpbin.org/stream/3' ) ;
await read ( response . body ) ;
} catch ( err ) {
console . error ( err . stack ) ;
} import fetch from 'node-fetch' ;
const response = await fetch ( 'https://github.com/' ) ;
console . log ( response . ok ) ;
console . log ( response . status ) ;
console . log ( response . statusText ) ;
console . log ( response . headers . raw ( ) ) ;
console . log ( response . headers . get ( 'content-type' ) ) ; Ao contrário dos navegadores, você pode acessar os cabeçalhos de Set-Cookie em conjunto manualmente usando Headers.raw() . Esta é uma API apenas node-fetch .
import fetch from 'node-fetch' ;
const response = await fetch ( 'https://example.com' ) ;
// Returns an array of values, instead of a string of comma-separated values
console . log ( response . headers . raw ( ) [ 'set-cookie' ] ) ; import fetch , {
Blob ,
blobFrom ,
blobFromSync ,
File ,
fileFrom ,
fileFromSync ,
} from 'node-fetch'
const mimetype = 'text/plain'
const blob = fileFromSync ( './input.txt' , mimetype )
const url = 'https://httpbin.org/post'
const response = await fetch ( url , { method : 'POST' , body : blob } )
const data = await response . json ( )
console . log ( data )A Fetting de Nó vem com uma implementação de dados formados compatível com especifica
import fetch , { FormData , File , fileFrom } from 'node-fetch'
const httpbin = 'https://httpbin.org/post'
const formData = new FormData ( )
const binary = new Uint8Array ( [ 97 , 98 , 99 ] )
const abc = new File ( [ binary ] , 'abc.txt' , { type : 'text/plain' } )
formData . set ( 'greeting' , 'Hello, world!' )
formData . set ( 'file-upload' , abc , 'new name.txt' )
const response = await fetch ( httpbin , { method : 'POST' , body : formData } )
const data = await response . json ( )
console . log ( data )Se, por algum motivo, precisar postar um fluxo proveniente de qualquer local arbitrário, poderá anexar um item de blob ou um item parecido com um arquivo.
O requisito mínimo é que ele tenha:
Symbol.toStringTag getter ou propriedade que é Blob ou Filestream() ou um método arrayBuffer() que retorna um ArrayBuffer. O stream() deve retornar qualquer objeto assíncrono, desde que produza UINT8Array (ou Buffer) So Node.Leablelable Streams e Whatwg Streams funcionam bem.
formData . append ( 'upload' , {
[ Symbol . toStringTag ] : 'Blob' ,
size : 3 ,
* stream ( ) {
yield new Uint8Array ( [ 97 , 98 , 99 ] )
} ,
arrayBuffer ( ) {
return new Uint8Array ( [ 97 , 98 , 99 ] ) . buffer
}
} , 'abc.txt' ) Você pode cancelar solicitações com AbortController . Uma implementação sugerida é abort-controller .
Um exemplo de cronometrar uma solicitação após 150ms pode ser alcançado como o seguinte:
import fetch , { AbortError } from 'node-fetch' ;
// AbortController was added in node v14.17.0 globally
const AbortController = globalThis . AbortController || await import ( 'abort-controller' )
const controller = new AbortController ( ) ;
const timeout = setTimeout ( ( ) => {
controller . abort ( ) ;
} , 150 ) ;
try {
const response = await fetch ( 'https://example.com' , { signal : controller . signal } ) ;
const data = await response . json ( ) ;
} catch ( error ) {
if ( error instanceof AbortError ) {
console . log ( 'request was aborted' ) ;
}
} finally {
clearTimeout ( timeout ) ;
}Consulte casos de teste para obter mais exemplos.
url uma string representando o URL para buscaroptions para a solicitação HTTP (s)Promise<Response>Execute uma busca http (s).
url deve ser um URL absoluto, como https://example.com/ . Um URL relativo de caminho ( /file/under/root ) ou URL-relativo de protocolo ( //can-be-http-or-https.com/ ) resultará em uma Promise rejeitada.
Os valores padrão são mostrados após cada tecla de opção.
{
// These properties are part of the Fetch Standard
method : 'GET' ,
headers : { } , // Request headers. format is the identical to that accepted by the Headers constructor (see below)
body : null , // Request body. can be null, or a Node.js Readable stream
redirect : 'follow' , // Set to `manual` to extract redirect headers, `error` to reject redirect
signal : null , // Pass an instance of AbortSignal to optionally abort requests
// The following properties are node-fetch extensions
follow : 20 , // maximum redirect count. 0 to not follow redirect
compress : true , // support gzip/deflate content encoding. false to disable
size : 0 , // maximum response body size in bytes. 0 to disable
agent : null , // http(s).Agent instance or function that returns an instance (see below)
highWaterMark : 16384 , // the maximum number of bytes to store in the internal buffer before ceasing to read from the underlying resource.
insecureHTTPParser : false // Use an insecure HTTP parser that accepts invalid HTTP headers when `true`.
} Se nenhum valores forem definidos, os seguintes cabeçalhos de solicitação serão enviados automaticamente:
| Cabeçalho | Valor |
|---|---|
Accept-Encoding | gzip, deflate, br (quando options.compress === true ) |
Accept | */* |
Content-Length | (calculado automaticamente, se possível) |
Host | (Informações do host e porta do URI alvo) |
Transfer-Encoding | chunked (quando req.body é um riacho) |
User-Agent | node-fetch |
Nota: Quando body é um Stream , Content-Length não é definido automaticamente.
A opção agent permite especificar opções relacionadas à rede que estão fora do escopo da busca, incluindo e não limitadas ao seguinte:
Consulte http.Agent para obter mais informações.
Se nenhum agente for especificado, o agente padrão fornecido pelo Node.js será usado. Observe que isso mudou no Node.js 19 para ter keepalive TRUE por padrão. Se você deseja ativar keepalive em uma versão anterior do Node.js, pode substituir o agente conforme a amostra de código a seguir.
Além disso, a opção agent aceita uma função que retorna http (s) .Agent Instância agente, dada a URL atual, isso é útil durante uma cadeia de redirecionamento no protocolo HTTP e HTTPS.
import http from 'node:http' ;
import https from 'node:https' ;
const httpAgent = new http . Agent ( {
keepAlive : true
} ) ;
const httpsAgent = new https . Agent ( {
keepAlive : true
} ) ;
const options = {
agent : function ( _parsedURL ) {
if ( _parsedURL . protocol == 'http:' ) {
return httpAgent ;
} else {
return httpsAgent ;
}
}
} ; O fluxo no Node.js possui um tamanho de buffer interno menor (16kb, também conhecido como highWaterMark ) dos navegadores do lado do cliente (> 1 MB, não consistentes entre os navegadores). Por esse motivo, quando você está escrevendo um aplicativo isomórfico e usando res.clone() , ele ficará com grande resposta no nó.
A maneira recomendada de corrigir esse problema é resolver a resposta clonada em paralelo:
import fetch from 'node-fetch' ;
const response = await fetch ( 'https://example.com' ) ;
const r1 = response . clone ( ) ;
const results = await Promise . all ( [ response . json ( ) , r1 . text ( ) ] ) ;
console . log ( results [ 0 ] ) ;
console . log ( results [ 1 ] ) ; Se por algum motivo você não gostar da solução acima, pois 3.x você poderá modificar a opção highWaterMark :
import fetch from 'node-fetch' ;
const response = await fetch ( 'https://example.com' , {
// About 1MB
highWaterMark : 1024 * 1024
} ) ;
const result = await res . clone ( ) . arrayBuffer ( ) ;
console . dir ( result ) ; Passado para a opção insecureHTTPParser no http (s) .request. Consulte http.request para obter mais informações.
O redirect: 'manual' para a Fetch Node é diferente do navegador e especificação, o que resulta em uma resposta filtrada opaca-redirecionada. A Fetch de nó fornece a resposta filtrada básica típica.
import fetch from 'node-fetch' ;
const response = await fetch ( 'https://httpbin.org/status/301' , { redirect : 'manual' } ) ;
if ( response . status === 301 || response . status === 302 ) {
const locationURL = new URL ( response . headers . get ( 'location' ) , response . url ) ;
const response2 = await fetch ( locationURL , { redirect : 'manual' } ) ;
console . dir ( response2 ) ;
}Uma solicitação HTTP (s) contendo informações sobre URL, método, cabeçalhos e o corpo. Esta classe implementa a interface do corpo.
Devido à natureza do Node.js, as seguintes propriedades não são implementadas neste momento:
typedestinationmodecredentialscacheintegritykeepaliveSão fornecidas as seguintes propriedades de extensão de fusão de nó:
followcompresscounteragenthighWaterMarkConsulte Opções para obter o significado exato dessas extensões.
(compatível com especificações)
input uma string representando um URL ou outra Request (que será clonada)options para a solicitação HTTP (s) Construa um novo objeto Request . O construtor é idêntico ao do navegador.
Na maioria dos casos, fetch(url, options) é mais simples do que criar um objeto Request .
Uma resposta HTTP (s). Esta classe implementa a interface do corpo.
As seguintes propriedades não são implementadas no Node-Fetch neste momento:
trailer(compatível com especificações)
body uma String ou fluxo Readableoptions um dicionário de opções ResponseInit Construa um novo objeto Response . O construtor é idêntico ao do navegador.
Como o Node.js não implementa trabalhadores de serviço (para os quais essa classe foi projetada), raramente é preciso construir uma Response diretamente.
(compatível com especificações)
Propriedade de conveniência representando se a solicitação terminou normalmente. Avaliará como verdadeiro se o status da resposta for maior ou igual a 200, mas menor que 300.
(compatível com especificações)
Propriedade de conveniência representando se a solicitação foi redirecionada pelo menos uma vez. Avaliará como verdadeiro se o contador de redirecionamento interno for maior que 0.
(Desvio da Spec)
Propriedade de conveniência que representa o tipo de resposta. A Fetch de nó suporta apenas 'default' e 'error' e não usa respostas filtradas.
Esta classe permite manipular e iterar um conjunto de cabeçalhos HTTP. Todos os métodos especificados no padrão de busca são implementados.
(compatível com especificações)
init para preencher o objeto Headers Construa um novo objeto Headers . init pode ser null , um objeto Headers , um objeto de mapa de valor-chave ou qualquer objeto iterável.
// Example adapted from https://fetch.spec.whatwg.org/#example-headers-class
import { Headers } from 'node-fetch' ;
const meta = {
'Content-Type' : 'text/xml'
} ;
const headers = new Headers ( meta ) ;
// The above is equivalent to
const meta = [ [ 'Content-Type' , 'text/xml' ] ] ;
const headers = new Headers ( meta ) ;
// You can in fact use any iterable objects, like a Map or even another Headers
const meta = new Map ( ) ;
meta . set ( 'Content-Type' , 'text/xml' ) ;
const headers = new Headers ( meta ) ;
const copyOfHeaders = new Headers ( headers ) ; Body é uma interface abstrata com métodos aplicáveis às classes Request e Response .
(Desvio da Spec)
Readable node.js Os dados são encapsulados no objeto Body . Observe que, embora o padrão de busca exija que a propriedade sempre seja uma ReadableStream Whatwg, na F-Fitch, é um fluxo Readable node.js.
(compatível com especificações)
BooleanUma propriedade booleana para se esse órgão tiver sido consumido. De acordo com as especificações, um corpo consumido não pode ser usado novamente.
fetch vem com métodos para analisar cargas úteis multipart/form-data bem como órgãos x-www-form-urlencoded usando .formData() Isso vem da idéia de que o trabalhador do serviço pode interceptar essas mensagens antes de ser enviado ao servidor para alterá-las. Isso é útil para qualquer pessoa que construa um servidor para que você possa usá -lo para analisar e consumir cargas úteis.
import http from 'node:http'
import { Response } from 'node-fetch'
http . createServer ( async function ( req , res ) {
const formData = await new Response ( req , {
headers : req . headers // Pass along the boundary value
} ) . formData ( )
const allFields = [ ... formData ]
const file = formData . get ( 'uploaded-files' )
const arrayBuffer = await file . arrayBuffer ( )
const text = await file . text ( )
const whatwgReadableStream = file . stream ( )
// other was to consume the request could be to do:
const json = await new Response ( req ) . json ( )
const text = await new Response ( req ) . text ( )
const arrayBuffer = await new Response ( req ) . arrayBuffer ( )
const blob = await new Response ( req , {
headers : req . headers // So that `type` inherits `Content-Type`
} . blob ( )
} )(Extensão de fusão de nó)
Um erro operacional no processo de busca. Consulte Erros-Handling.md para obter mais informações.
(Extensão de fusão de nó)
Um erro lançado quando a solicitação é abortada em resposta ao evento abort de um AbortSignal . Possui uma propriedade de name da AbortError . Consulte Erros-Handling.md para obter mais informações.
Como os tipos 3.x são agrupados com node-fetch , para que você não precise instalar pacotes adicionais.
Para versões mais antigas, use as definições de tipo de definitivamente time:
npm install --save-dev @types/[email protected]Graças ao Github/busca por fornecer uma sólida referência de implementação.
 |  |  |  |  |
|---|---|---|---|---|
| David Frank | Jimmy Wärting | Antoni Kepinski | Richie Bendall | Gregor Martynus |
Mit
