@achingbrain/node-fetch 中文文档教程

Question

Temporary fork ????

这是 node-fetch 的临时分支，合并了来自 node-fetch#1172 的修复。 它不会被更新或维护。

node-fetch

将 window.fetch 引入 Node.js 的轻量级模块

（我们正在寻找 v2 维护者和合作者)

• Motivation
• Features
• Difference from client-side fetch
• Installation
• Loading and configuring the module
• Common Usage
  • Plain text or HTML
  • JSON
  • Simple Post
  • Post with JSON
  • Post with form parameters
  • Handling exceptions
  • Handling client and server errors
• Advanced Usage
  • Streams
  • Buffer
  • Accessing Headers and other Meta data
  • Extract Set-Cookie Header
  • Post data using a file stream
  • Post with form-data (detect multipart)
  • Request cancellation with AbortSignal
• API
  • fetch(url[, options])
  • Options
  • Class: Request
  • Class: Response
  • Class: Headers
  • Interface: Body
  • Class: FetchError
• License
• Acknowledgement

Motivation

而不是在 Node.js 中实现 XMLHttpRequest 以运行特定于浏览器的 Fetch polyfill，为什么不直接从原生 http 到 fetch API？ 因此，node-fetch 是 Node.js 运行时上 window.fetch 兼容 API 的最小代码。

请参阅 Matt Andrews 的 isomorphic-fetch 或 Leonardo Quixada 的 cross-fetch 用于同构使用（为服务器端导出 node-fetch，为客户端导出 whatwg-fetch）。

Features

• Stay consistent with window.fetch API.
• Make conscious trade-off when following WHATWG fetch spec and stream spec implementation details, document known differences.
• Use native promise but allow substituting it with [insert your favorite promise library].
• Use native Node streams for body on both request and response.
• Decode content encoding (gzip/deflate) properly and convert string output (such as res.text() and res.json()) to UTF-8 automatically.
• Useful extensions such as timeout, redirect limit, response size limit, explicit errors for troubleshooting.

Difference from client-side fetch

• See Known Differences for details.
• If you happen to use a missing feature that window.fetch offers, feel free to open an issue.
• Pull requests are welcomed too!

Installation

当前稳定版本 (2.x)

$ npm install node-fetch

Loading and configuring the module

我们建议您通过 require 加载模块，直到 ES 模块在 node 中稳定：

const fetch = require('node-fetch');

如果您使用的是原生以外的 Promise 库，通过 fetch.Promise 设置它：

const Bluebird = require('bluebird');

fetch.Promise = Bluebird;

Common Usage

注意：下面的文档是最新的 2.x 版本； 请参阅 1.x 自述文件，更新日志 和 2.x 升级差异指南。

Plain text or HTML

fetch('https://github.com/')
    .then(res => res.text())
    .then(body => console.log(body));

JSON

fetch('https://api.github.com/users/github')
    .then(res => res.json())
    .then(json => console.log(json));

Simple Post

fetch('https://httpbin.org/post', { method: 'POST', body: 'a=1' })
    .then(res => res.json()) // expecting a json response
    .then(json => console.log(json));

Post with JSON

const body = { a: 1 };

fetch('https://httpbin.org/post', {
        method: 'post',
        body:    JSON.stringify(body),
        headers: { 'Content-Type': 'application/json' },
    })
    .then(res => res.json())
    .then(json => console.log(json));

Post with form parameters

从 v7.5.0 开始，URLSearchParams 在 Node.js 中可用。 更多使用方法见官方文档。

注意：Content-Type 标头仅在 URLSearchParams 实例给出时自动设置为 x-www-form-urlencoded：

const { URLSearchParams } = require('url');

const params = new URLSearchParams();
params.append('a', 1);

fetch('https://httpbin.org/post', { method: 'POST', body: params })
    .then(res => res.json())
    .then(json => console.log(json));

Handling exceptions

注意：3xx-5xx 响应是NOT 异常，应该在then() 中处理； 有关详细信息，请参阅下一节。

在 fetch promise 链中添加一个 catch 将捕获 所有 异常，例如来自节点核心库的错误、网络错误和操作错误，这些都是 FetchError 的实例。 有关详细信息，请参阅错误处理文档。

fetch('https://domain.invalid/')
    .catch(err => console.error(err));

Handling client and server errors

通常创建一个辅助函数来检查响应是否不包含客户端 (4xx) 或服务器 (5xx) 错误响应：

function checkStatus(res) {
    if (res.ok) { // res.status >= 200 && res.status < 300
        return res;
    } else {
        throw MyCustomError(res.statusText);
    }
}

fetch('https://httpbin.org/status/400')
    .then(checkStatus)
    .then(res => console.log('will not get here...'))

Advanced Usage

Streams

“Node.js 方式”是尽可能使用流：

fetch('https://assets-cdn.github.com/images/modules/logos_page/Octocat.png')
    .then(res => {
        const dest = fs.createWriteStream('./octocat.png');
        res.body.pipe(dest);
    });

在 Node.js 14 中，您还可以使用读取 body 的异步迭代器； 但是，要小心抓住 错误——响应运行的时间越长，遇到错误的可能性就越大。

const fetch = require('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);
}

在 Node.js 12 中，您还可以使用异步迭代器来读取 body； 然而，带有流的异步迭代器 直到 Node.js 14 才成熟，所以你需要做一些额外的工作来确保你处理错误 直接从流中等待它响应完全关闭。

const fetch = require('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);
}

Buffer

如果您更喜欢完整缓存二进制数据，请使用 buffer()。 （注意：buffer() 是一个 node-fetch-only API）

const fileType = require('file-type');

fetch('https://assets-cdn.github.com/images/modules/logos_page/Octocat.png')
    .then(res => res.buffer())
    .then(buffer => fileType(buffer))
    .then(type => { /* ... */ });

Accessing Headers and other Meta data

fetch('https://github.com/')
    .then(res => {
        console.log(res.ok);
        console.log(res.status);
        console.log(res.statusText);
        console.log(res.headers.raw());
        console.log(res.headers.get('content-type'));
    });

Extract Set-Cookie Header

与浏览器不同，您可以使用 Set-Cookie 手动访问原始标头 <代码>标题.raw()。 这是一个仅限 node-fetch 的 API。

fetch(url).then(res => {
    // returns an array of values, instead of a string of comma-separated values
    console.log(res.headers.raw()['set-cookie']);
});

Post data using a file stream

const { createReadStream } = require('fs');

const stream = createReadStream('input.txt');

fetch('https://httpbin.org/post', { method: 'POST', body: stream })
    .then(res => res.json())
    .then(json => console.log(json));

Post with form-data (detect multipart)

const FormData = require('form-data');

const form = new FormData();
form.append('a', 1);

fetch('https://httpbin.org/post', { method: 'POST', body: form })
    .then(res => res.json())
    .then(json => console.log(json));

// OR, using custom headers
// NOTE: getHeaders() is non-standard API

const form = new FormData();
form.append('a', 1);

const options = {
    method: 'POST',
    body: form,
    headers: form.getHeaders()
}

fetch('https://httpbin.org/post', options)
    .then(res => res.json())
    .then(json => console.log(json));

Request cancellation with AbortSignal

注意：您只能在 Node >= v8.0.0 上取消流请求

您可以使用 AbortController 取消请求。 建议的实施方式是 abort-controller。

请求在 150 毫秒后超时的示例如下所示：

import AbortController from 'abort-controller';

const controller = new AbortController();
const timeout = setTimeout(
  () => { controller.abort(); },
  150,
);

fetch(url, { signal: controller.signal })
  .then(res => res.json())
  .then(
    data => {
      useData(data)
    },
    err => {
      if (err.name === 'AbortError') {
        // request was aborted
      }
    },
  )
  .finally(() => {
    clearTimeout(timeout);
  });

参见 测试用例< /a> 更多示例。

API

fetch(url[, options])

• url A string representing the URL for fetching
• options Options for the HTTP(S) request
• Returns: Promise<[Response](#class-response)>

执行 HTTP(S) 提取。

url应该是一个绝对的url，比如https://example.com/。 将产生路径相对 URL (/file/under/root) 或协议相对 URL (//can-be-http-or-https.com/)在被拒绝的 Promise 中。

Options

默认值显示在每个选项键之后。

{
    // 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, a string, a Buffer, a Blob, 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
    timeout: 0,         // req/res timeout in ms, it resets on redirect. 0 to disable (OS limit applies). Signal is recommended instead.
    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)
}

Default Headers

如果没有设置任何值，将自动发送以下请求头：

Header	Value
Accept-Encoding	gzip,deflate (when options.compress === true)
Accept	*/*
Connection	close (when no options.agent is present)
Content-Length	(automatically calculated, if possible)
Transfer-Encoding	chunked (when req.body is a stream)
User-Agent	node-fetch/1.0 (+https://github.com/bitinn/node-fetch)

注意：当body 是一个Stream 时，Content-Length 没有设置自动地。

Custom Agent

agent 选项允许您指定超出 Fetch 范围的网络相关选项，包括但不限于以下内容：

• Support self-signed certificate
• Use only IPv4 or IPv6
• Custom DNS Lookup

参见 http.Agent 了解更多信息。

此外，agent 选项接受返回 http(s).Agent 给定当前 URL，这在跨 HTTP 和 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;
        }
    }
}

Class: Request

包含有关 URL、方法、标头和正文的信息的 HTTP(S) 请求。 这个类实现了Body 接口。

由于 Node.js 的性质，目前未实现以下属性：

• type
• destination
• referrer
• referrerPolicy
• mode
• credentials
• cache
• integrity
• keepalive

提供了以下节点提取扩展属性：

• follow
• compress
• counter
• agent

请参阅 options 以了解其确切含义这些扩展。

new Request(input[, options])

(spec-compliant)

• input A string representing a URL, or another Request (which will be cloned)
• options [Options][#fetch-options] for the HTTP(S) request

构造一个新的 Request 对象。 构造函数与浏览器中的构造函数相同。

在大多数情况下，直接 fetch(url, options) 比创建一个 Request 对象更简单。

Class: Response

HTTP(S) 响应。 这个类实现了Body 接口。

以下属性目前未在 node-fetch 中实现：

• Response.error()
• Response.redirect()
• type
• trailer

new Response([body[, options]])

(spec-compliant)

• body A String or Readable stream
• options A ResponseInit options dictionary

构造一个新的 Response 对象。 构造函数与浏览器中的构造函数相同。

因为 Node.js 不实现服务工作者（此类是为其设计的），所以很少需要直接构造 Response。

response.ok

(spec-compliant)

表示请求是否正常结束的便利属性。 如果响应状态大于或等于 200 但小于 300，则计算结果为真。

response.redirected

(spec-compliant)

表示请求是否至少被重定向的便利属性一次。 如果内部重定向计数器大于 0，则计算结果为真。

Class: Headers

此类允许对一组 HTTP 标头进行操作和迭代。 Fetch Standard 中指定的所有方法均已实现。

new Headers([init])

(spec-compliant)

• init Optional argument to pre-fill the Headers object

构造一个新的 Headers 对象。 init 可以是 null、Headers 对象、键值映射对象或任何可迭代对象。

// Example adapted from https://fetch.spec.whatwg.org/#example-headers-class

const meta = {
  'Content-Type': 'text/xml',
  'Breaking-Bad': '<3'
};
const headers = new Headers(meta);

// The above is equivalent to
const meta = [
  [ 'Content-Type', 'text/xml' ],
  [ 'Breaking-Bad', '<3' ]
];
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');
meta.set('Breaking-Bad', '<3');
const headers = new Headers(meta);
const copyOfHeaders = new Headers(headers);

Interface: Body

Body 是一个抽象接口，其方法适用于 Request 和 Response类。

目前node-fetch中还没有实现以下方法：

• formData()

body.body

(deviation from spec)

• Node.js Readable stream

数据封装在Body对象中。 请注意，虽然 Fetch Standard 要求属性始终是 WHATWG ReadableStream，但在 node-fetch 中它是一个 Node.js Readable 流。

body.bodyUsed

(spec-compliant)

• Boolean

一个布尔属性，表示这个身体是否已经被消耗。 根据规格，消耗的身体不能再次使用。

body.arrayBuffer()

body.blob()

body.json()

body.text()

(spec-compliant)

• Returns: Promise

使用正文并返回将解析为其中一种格式的承诺。

body.buffer()

(node-fetch extension)

• Returns: Promise<Buffer>

使用正文并返回将解析为 Buffer 的承诺。

body.textConverted()

(node-fetch extension)

• Returns: Promise<String>

与 body.text() 相同，只是不总是转换为 UTF-8，而是执行编码嗅探如果可能，将文本转换为 UTF-8。

（此 API 需要 npm 包 encoding 的可选依赖项，您需要手动安装。webpack 用户可能会看到 警告消息 由于此可选依赖项。）

Class: FetchError

(node-fetch extension)

抓取过程中的操作错误。 有关详细信息，请参阅 ERROR-HANDLING.md。

Class: AbortError

(node-fetch extension)

当响应 AbortSignal 中止请求时抛出的错误 的 abort 事件。 它具有 AbortError 的 name 属性。 有关详细信息，请参阅 ERROR-HANDLING.MD。

Acknowledgement

感谢 github/fetch 提供可靠的实现参考。

node-fetch v1 由 @bitinn 维护； v2 由 @TimothyGu、@bitinn 和@jimmywarting； v2 自述文件由 @jkantr 编写。

License

麻省理工学院

[mdn-headers]：https://developer.mozilla.org/en-US/docs/Web/API/Headers