动机
而不是执行 XMLHttpRequest 在节点.js中运行特定浏览器 获取多填充,为什么不从本地去 http 改为 fetch API直接吗? 因此, node-fetch,最小代码 window.fetch 在 Node.js 运行时间上兼容 API.
见杰森·米勒的 同位素不匹配 或者莱昂纳多·克萨达的 横切 同位素用途(出口) node-fetch 用于服务器侧, whatwg-fetch 客户端).
特征
- 保持与
window.fetchAPI (英语). - 跟踪时自觉权衡 WhatWG 获取光谱 财务报告和审定财务报表 流谱 实施细节,记录已知差异.
- 使用本地承诺和同步函数 .
- 在请求和响应时使用本地的节点流来表示身体.
- 正确解码内容编码(gzip/deflate/brotli),并转换字符串输出(例如)
res.text()财务报告和审定财务报表res.json())自动到UTF-8. - 有用的扩展,如重定向限制,响应大小限制, 明显错误 解决麻烦.
客户端获取的差异
安装
目前稳定的释放量3.x(中文(简体) )
npm install node-fetch
装入和配置模块
// CommonJS
const fetch = require('node-fetch');
// ES Module
import fetch from 'node-fetch';
如果您要在节点中补齐全局对象 :
const fetch = require('node-fetch');
if (!globalThis.fetch) {
globalThis.fetch = fetch;
}
对于早于12年的节点版本,请使用此工具 globalThis 多边填充。 。 。 .
升级
使用旧版本的节点? 请检查以下文件 :
常见用途
注:以下文件为最新资料: 3.x 请检查date=中的日期值 (帮助) 升级。 。 。 .
纯文本或 HTML
const fetch = require('node-fetch');
const response = await fetch('https://github.com/');
const body = await response.text();
console.log(body);
贾森
const fetch = require('node-fetch');
const response = await fetch('https://api.github.com/users/github');
const data = await response.json();
console.log(data);
简单员额
const fetch = require('node-fetch');
const response = await fetch('https://httpbin.org/post', {method: 'POST', body: 'a=1'});
const data = await response.json();
console.log(data);
带 JSON 的帖子
const fetch = require('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 在 Node.js 中的全局对象上可获取,截至v10.0.0。 见 正式文件 对于更多的使用方法.
注: Content-Type 标题只自动设定为 x-www-form-urlencoded 当一个实例 URLSearchParams 规定如下:
const fetch = require('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);
处理例外
注:3xxx-5xx的答复是: 没有 例外情况,应在 then(),参见下一节.
将获取函数包成一个 try/catch 块会赶上 全部 例外,例如来自节点核心库的错误,例如网络错误,以及操作错误,这些都是FeferError的例子。 见 错误处理文档 更多细节.
const fetch = require('node-fetch');
try {
await fetch('https://domain.invalid/');
} catch (error) {
console.log(error);
}
处理客户端和服务器错误
常见的是创建帮助器功能来检查响应是否包含没有客户端(4xx)或服务器(5xx)错误响应:
const fetch = require('node-fetch');
class HTTPResponseError extends Error {
constructor(response, ...args) {
this.response = response;
super(`HTTP Error Response: ${response.status} ${response.statusText}`, ...args);
}
}
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}`);
}
处理饼干
饼干不是默认保存的. 然而,饼干可以通过操纵请求和响应头来取出并传递. 见 提取 Set- Cookie 页眉 详细情况.
高级使用
流线
"Node.js way"是在可能的情况下使用溪流. 你会吹管子 res.body 到另一个溪流。 此示例使用 流. 管线 以附加流出错处理器,并等待下载完成.
const {createWriteStream} = require('fs');
const {pipeline} = require('stream');
const {promisify} = require('util');
const fetch = require('node-fetch');
const streamPipeline = promisify(pipeline);
const response = await fetch('https://assets-cdn.github.com/images/modules/logos_page/Octocat.png');
if (!response.ok) throw new Error(`unexpected response ${response.statusText}`);
await streamPipeline(response.body, createWriteStream('./octocat.png'));
在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; 然而, 串行者与溪流
直到节点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);
}
缓冲
如果您喜欢全部缓存二进制数据,请使用缓冲 (). (注:缓冲()是一种 node-fetch 只有API)
const fetch = require('node-fetch');
const fileType = require('file-type');
const response = await fetch('https://octodex.github.com/images/Fintechtocat.png');
const buffer = await response.buffer();
const type = await fileType.fromBuffer(buffer)
console.log(type);
访问信头和其他 Meta 数据
const fetch = require('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'));
提取 Set- Cookie 页眉
与浏览器不同, 您可以访问原始 Set-Cookie 手动使用页眉 Headers.raw()。这是 node-fetch 仅限API.
const fetch = require('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']);
使用文件流发送数据
const {createReadStream} = require('fs');
const fetch = require('node-fetch');
const stream = createReadStream('input.txt');
const response = await fetch('https://httpbin.org/post', {method: 'POST', body: stream});
const data = await response.json();
console.log(data)
带有窗体数据( 检测多部分) 的邮箱
const fetch = require('node-fetch');
const FormData = require('form-data');
const form = new FormData();
form.append('a', 1);
const response = await fetch('https://httpbin.org/post', {method: 'POST', body: form});
const data = await response.json();
console.log(data)
// OR, using custom headers
// NOTE: getHeaders() is non-standard API
const options = {
method: 'POST',
body: form,
headers: form.getHeaders()
};
const response = await fetch('https://httpbin.org/post', options);
const data = await response.json();
console.log(data)
节点比对还支持符合光谱的FormData执行,例如 窗体数据 财务报告和审定财务报表 窗体数据节点数字 :
const fetch = require('node-fetch');
const FormData = require('formdata-node');
const form = new FormData();
form.set('greeting', 'Hello, world!');
const response = await fetch('https://httpbin.org/post', {method: 'POST', body: form});
const data = await response.json();
console.log(data);
请求取消终止符号
您可以取消请求 AbortController建议的执行是: abort-controller。 。 。 .
150毫秒后取消请求的一个实例如下:
const fetch = require('node-fetch');
const AbortController = require('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 fetch.AbortError) {
console.log('request was aborted');
}
} finally {
clearTimeout(timeout);
}
见 测试案例 需要更多的实例.
API 密码
获取( url[, 选项])
执行 HTTP( S) 获取 .
url 应该是一个绝对的url,例如 https://example.com/。路径相对的 URL (/file/under/root)或协议相对的 URL(//can-be-http-or-https.com/)将导致被拒绝 Promise。 。 。 .
选项
默认值在每个选项密钥后显示 .
{
// 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
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`.
}
默认信头
如果没有设置值,则将自动发送下列请求头:
| 页眉 | 数值 |
|---|---|
Accept-Encoding | gzip,deflate,br (当 options.compress === true(中文(简体) ) |
Accept | */* |
Connection | close (无时) options.agent 已存在) |
Content-Length | (如有可能,自动计算) |
Transfer-Encoding | chunked (当 req.body 是一个溪流) |
User-Agent | node-fetch |
注:何时 body 是一个 Stream, (中文(简体) ), Content-Length 未自动设置.
自定义代理
这个 agent 选项允许您指定不属于“获取”范围的联网相关选项,包括但不限于以下选项:
- 支持自签名证书
- 只使用 IPv4 或 IPv6
- 自定义 DNS 查询
见 http.Agent 更多信息.
此外 agent 选项接受返回的函数 http(s) 减少.Agent 实例为当前 網址,这在跨 HTTP 和 HTTPS 协议的重定向链中有用.
const http = require('http');
const https = require('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;
}
}
};
自定义高水母
节点上流出的内部缓冲器尺寸较小(16kB, aka) highWaterMark)来自客户端浏览器(>1MB,浏览器之间不一致). 因此,当你写一个异形的应用程序和使用 res.clone(),它会在节点中与大响应相挂起.
建议解决这一问题的方法是同时解决克隆反应:
const fetch = require('node-fetch');
const response = await fetch('https://example.com');
const r1 = await response.clone();
const results = await Promise.all([response.json(), r1.text()]);
console.log(results[0]);
console.log(results[1]);
如果你出于某种原因 不喜欢上面的解决方案,因为 3.x 您可以修改 highWaterMark 选项 :
const fetch = require('node-fetch');
const response = await fetch('https://example.com', {
// About 1MB
highWaterMark: 1024 * 1024
});
const result = await res.clone().buffer();
console.dir(result);
不安全的 HTTP 解析器
路过 insecureHTTPParser 。请求。 见 http.request 更多信息.
类: 请求
HTTP( S) 请求, 包含关于 URL 、 方法、 标题和 机构 的信息 。 此类执行 体质 接口.
由于节点(Node.js)的性质,目前尚未执行以下属性:
typedestinationreferrerreferrerPolicymodecredentialscacheintegritykeepalive
提供了以下节点扩展属性:
followcompresscounteragenthighWaterMark
见 选项 用于这些扩展的确切含义.
新请求(输入[,选项])
(符合规格)
input代表 URL 的字符串,或者另一个Request(将被克隆)optionsHTTP( S) 请求的[可选 [# fetch- options]
构造一个新的 Request 对象。 构造器与 浏览器。 。 。 .
在大多数情况下,直接 fetch(url, options) 简单于创建 Request 对象.
类别:回应
HTTP( S) 响应 。 此类执行 体质 接口.
此时节点不执行以下属性 :
trailer
新的反应([机构][,选项)])
(符合规格)
bodyA 类String或者说Readable流线optionsA 类ResponseInit选项词典
构造一个新的 Response 对象。 构造器与 浏览器。 。 。 .
由于Node.js不实施服务工人(为服务工人设计了这一类),人们很少需要建造一个 Response 直接说.
答复
(符合规格)
代表请求正常结束的方便财产。 如果答复情况大于或等于200,但小于300,将进行真实评价.
回复
(符合规格)
代表请求至少重新定向一次的方便财产。 如果内部重定向计数器大于0.
响应。类型
(来自 spec 的缩写)
代表响应类型的方便属性。 节点比对只支持 'default' 财务报告和审定财务报表 'error' 而不使用 过滤的响应。 。 。 .
类: 页眉
此类允许在一组HTTP头上进行操纵并活化. 《公约》中规定的所有方法 获取标准 已执行.
新标题( [init] )
(符合规格)
init预填的可选参数Headers对象
构造新 Headers 对象. init 也可以这样 null页:1 Headers 对象、键值映射对象或任何可移动对象.
// Example adapted from https://fetch.spec.whatwg.org/#example-headers-class
const {Headers} = require('node-fetch');
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);
接口:正文
Body 是一个抽象的界面,与两种方法都适用 Request 财务报告和审定财务报表 Response 课程.
此时节点尚未实施以下方法: 1
formData()
躯体
(来自 spec 的缩写)
- 节点.js
Readable流线
数据封装在 Body 对象。 请注意,虽然 获取标准 要求财产永远是一个WhatWG ReadableStream在节点和节点之间 Readable 流线。 。 。 .
躯体
(符合规格)
Boolean
如果这具尸体被消耗了,那就意味着一个布尔的财产。 按照规格,一个被消耗的身体不能再被使用.
车体. 阵列缓冲 ()
机构. blob( )
机构.json()
文本( )
(符合规格)
- 回返情况:
Promise
将尸体收起来,并返回一个承诺,以决定其中的一种形式.
弹出器( )
(节点-牵引扩展)
- 回返情况:
Promise<Buffer>
收起尸体,把承诺还给缓冲器.
类: 获取错误
(节点-牵引扩展)
获取过程中的操作错误 。 见 错误的修复(MD) 需要更多信息.
类: 中止错误
(节点-牵引扩展)
请求因响应 AbortSignal是因为 abort 活动。 它有一个 name 财产 AbortError。见 (原始内容存档于2013-10-10). ERROR-HANDLING.MD 需要更多信息.
类型脚本
自兹 3.x 类型与 node-fetch,因此不需要安装任何额外的软件包.
对于旧版本,请使用来自 绝对是Tyed数字 :
npm install --save-dev @types/node-fetch
致谢
感谢 gi/牵引 提供坚实的执行参考.
团队
 |  |  |  |  |
|---|---|---|---|---|
| 大卫·弗兰克 | 吉米・沃丁 | 安东尼·克平斯基 | 里奇·本道尔 | 格雷戈·马蒂努斯 |