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

Question

electron-fetch

将 window.fetch 引入 Electron 后台进程的轻量级模块。 从 node-fetch 分叉。

Motivation

而不是通过 Electron 的 net 模块实现 XMLHttpRequest 来运行特定于浏览器的 Fetch polyfill，为什么不直接从原生 net.request 到 fetch API？ 因此 electron-fetch 是 Electron 后台运行时上 window.fetch 兼容 API 的最小代码。

为什么不简单地使用节点获取？ 好吧，Electron 的 net 模块在处理 Web 代理方面比 Node.js 的 http 模块做得更好。

Features

• Stay consistent with window.fetch API.
• Runs on both Electron and Node.js, using either Electron's net module, or Node.js http module as backend.
• Make conscious trade-off when following whatwg fetch spec and stream spec implementation details, document known difference.
• Use native promise.
• Use native stream 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 (when running on Node.js), 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!

Difference from node-fetch

• Removed node-fetch specific options, such as compression.
• Added electron-specific options to specify the Session & to enable using cookies from it.
• Added electron-specific option useElectronNet, which can be set to false when running on Electron in order to behave as Node.js.
• Removed possibility to use custom Promise implementation (it's 2018, Promise is available everywhere!).
• Removed the possibility to forbid content compression (incompatible with Electron's net module, and of limited interest)
• standard-ized the code.

Install

$ npm install electron-fetch --save

Usage

import fetch from 'electron-fetch'
// or
// const fetch = require('electron-fetch').default

// 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))

// catching network error
// 3xx-5xx responses are NOT network errors, and should be handled in then()
// you only need one catch() at the end of your promise chain

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

// stream
// the node.js way is to use stream when possible

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

// buffer
// if you prefer to cache binary data in full, use buffer()
// note that buffer() is a electron-fetch only API

import fileType from 'file-type'

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

// meta

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'))
    })

// post

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

// post with stream from file

import { createReadStream } from 'fs'

const stream = createReadStream('input.txt')
fetch('http://httpbin.org/post', { method: 'POST', body: stream })
    .then(res => res.json())
    .then(json => console.log(json))

// post with JSON

const body = { a: 1 }
fetch('http://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-data (detect multipart)

import FormData from 'form-data'

const form = new FormData()
form.append('a', 1)
fetch('http://httpbin.org/post', { method: 'POST', body: form })
    .then(res => res.json())
    .then(json => console.log(json))

// post with form-data (custom headers)
// note that getHeaders() is non-standard API

import FormData from 'form-data'

const form = new FormData()
form.append('a', 1)
fetch('http://httpbin.org/post', { method: 'POST', body: form, headers: form.getHeaders() })
    .then(res => res.json())
    .then(json => console.log(json))

// node 7+ with async function

(async function () {
    const res = await fetch('https://api.github.com/users/github')
    const json = await res.json()
    console.log(json)
})()

有关更多示例，请参阅测试用例。

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，比如http://example.com/。 将产生路径相对 URL (/file/under/root) 或协议相对 URL (//can-be-http-or-https.com/)在一个被拒绝的承诺中。

Options

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

const defaultOptions = {
    // 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', // (/!\ only works when running on Node.js) set to `manual` to extract redirect headers, `error` to reject redirect
    signal: null,       // the AbortSignal from an AbortController instance.

    // The following properties are electron-fetch extensions
    follow: 20,         // (/!\ only works when running on Node.js) 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)
    size: 0,            // maximum response body size in bytes. 0 to disable
    session: session.defaultSession, // (/!\ only works when running on Electron) Electron Session object.,
    agent: null,        // (/!\ only works when useElectronNet is false) Node HTTP Agent.,
    useElectronNet: true, // When running on Electron, defaults to true. On Node.js, defaults to false and cannot be set to true.
    useSessionCookies: true, // (/!\ only works when running on Electron >= 7) Whether or not to automatically send cookies from session.,
    user: undefined,    // When running on Electron behind an authenticated HTTP proxy, username to use to authenticate
    password: undefined // When running on Electron behind an authenticated HTTP proxy, password to use to authenticate
}

Default Headers

如果未设置值，将自动发送以下请求标头：

Header	Value
Accept-Encoding	gzip,deflate
Accept	*/*
Connection	close
Content-Length	(automatically calculated, if possible)
User-Agent	electron-fetch/1.0 (+https://github.com/arantes555/electron-fetch)

Class: Request

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

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

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

提供了以下电子获取扩展属性：

• follow (/!\ only works when running on Node.js)
• counter (/!\ only works when running on Node.js)
• session (/!\ only works when running on Electron)
• agent (/!\ only works when running on Node.js)
• useElectronNet (/!\ only works when running on Electron, throws when set to true on Node.js)
• useSessionCookies (/!\ only works when running on Electron >= 7)

请参阅 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 接口。

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

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

new Response([body[, options]])

(spec-compliant)

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

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

因为 Node.js & Electron 的后台没有实现 service workers（为此设计了这个类），很少需要直接构造一个 Response。

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类。

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

• formData()

body.body

(deviation from spec)

• Node.js Readable stream

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

body.bodyUsed

(spec-compliant)

• Boolean

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

body.arrayBuffer()

body.blob()

body.json()

body.text()

(spec-compliant)

• Returns: Promise

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

body.buffer()

(electron-fetch extension)

• Returns: Promise<Buffer>

消费主体并返回将解析为缓冲区的承诺。

body.textConverted()

(electron-fetch extension)

• Returns: Promise<String>

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

Class: FetchError

(electron-fetch extension)

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

License

MIT

Acknowledgement

感谢 github/fetch 提供可靠的实施参考。 感谢 node-fetch 为 fork 提供了坚实的基础。

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