Got Promise API 实战指南:从基础请求、快捷解析到事件监听与请求取消

原创2026-09-21 15:04:271,951 阅读
文章标签:网络通信

Got Promise API 实战指南:从基础请求、快捷解析到事件监听与请求取消

Got 是一个面向 Node.js 的人性化、功能强大的 HTTP 请求库,其主入口函数返回一个可 await 的 Promise,同时该 Promise 上还额外挂载了 json()、buffer()、text() 三个快捷解析方法以及 on() / once() / off() 事件接口。本文以 documentation/1-promise.md 为骨架,结合仓库中的 Promise 实现源码、核心 Request 实现 与测试用例,系统讲解 Promise API 的调用签名、解析语义、事件系统、请求取消与底层运行机制,帮助你写出简洁、健壮、可观测的 Got 请求代码。

一、Promise API 概览:一次调用,两种能力

Got 主函数 got(...) 的返回值本质上是一个原生 Promise,但经过内部封装后,它同时具备两类能力:

  1. 标准 Promise 行为:可以直接 await,拿到完整的 Response 对象;请求失败时(如非 2xx/3xx 状态码、网络错误)会被 reject。
  2. 快捷解析能力:在 Promise 上追加 .json()、.buffer()、.text() 方法,返回“只含响应体”的派生 Promise。
  3. 事件监听能力:追加 .on()、.once()、.off() 方法,复用 Stream API 的事件体系(如 uploadProgress、downloadProgress、response、request、redirect)。

这意味着你既可以写 const response = await got(url) 拿完整响应元数据,也可以写 const data = await got(url).json() 直接拿解析后的数据,还可以在 await 之前挂上进度监听器做上传/下载进度上报——三种风格共用同一个 Promise 对象,互不冲突。

二、函数签名与基本用法

got(url: string | URL, options?: OptionsInit, defaults?: Options): Promise<Response>
  • url:请求地址,可以是字符串或 URL 实例,作为第一个参数传入。
  • options:OptionsInit,第二个参数,例如自定义 headers、method、signal 等。
  • defaults:可选的默认 Options 实例,通常由 got.extend() 内部使用,日常调用不需要关心。

最常见的写法是“第一个参数传 URL,第二个参数传选项”:

import got from 'got';

const {headers} = await got(
	'https://httpbin.org/anything',
	{
		headers: {
			foo: 'bar'
		}
	}
).json();

console.log(headers);
//=> {foo: 'bar', …}

从源码调用链看(source/create.ts),got(url, options) 会先构造一个 Request 实例,经过默认 handler 链处理后在内部 lastHandler 中调用 asPromise(request)(见 source/create.ts),最终返回一个 RequestPromise。也就是说,Promise API 与 Stream API 共享同一个 Request 内核,Promise 只是在其上包裹了一层“等响应结束后自动解析 body / 汇总错误”的逻辑。

2.1 HTTP 方法别名

除直接调用 got(url, options) 外,Got 还提供了 got.get、got.post、got.put、got.patch、got.head、got.delete、got.query 等别名(见 source/create.ts),它们内部等价于 got(url, {...options, method}):

// 以下两种写法语义相同
const a = await got.post('https://httpbin.org/anything', {json: {hello: 'world'}});
const b = await got('https://httpbin.org/anything', {method: 'POST', json: {hello: 'world'}});

三、三个快捷解析方法:json / buffer / text

Promise 上挂载了三个“只拿响应体”的快捷方法,它们都返回一个新的、派生的 RequestPromise,原 Promise 不受影响。

3.1 promise.json<T>()

返回:Promise<T>

返回解析后的 JSON 对象:

const {data} = await got.post('https://httpbin.org/anything', {
	json: {
		hello: 'world'
	}
}).json();

console.log(data);
//=> {"hello": "world"}

语义上等价于设置 resolveBodyOnly: true + responseType: 'json'(见 documentation/2-options.md#resolvebodyonly 与 documentation/2-options.md#responsetype)。

源码细节(source/as-promise/index.ts):.json() 还带一个“顺手”行为——如果请求尚未写完且未显式设置 accept 头,会自动补上 headers.accept = 'application/json',告诉服务端客户端期望 JSON 响应。

3.2 promise.buffer()

返回:Promise<Uint8Array>

返回原始字节的 Uint8Array(注意不是 Node 的 Buffer,而是标准 TypedArray):

const bytes = await got('https://httpbin.org/image/png').buffer();
console.log(bytes instanceof Uint8Array);
//=> true

语义上等价于 resolveBodyOnly: true + responseType: 'buffer'。

重要提示:buffer() 返回的是 rawBody 的引用而非拷贝。如果后续要修改它,请先用 new Uint8Array(buffer) 复制一份,否则会同时影响 .text() / .json() 的解析结果(见 documentation/2-options.md#responsetype 中的说明)。测试用例 test/promise.ts 也验证了在 decompress: false 时压缩响应返回的是 Uint8Array 而非 Buffer。

3.3 promise.text()

返回:Promise<string>

返回按指定 encoding 解码后的字符串(默认 utf8,见 documentation/2-options.md#encoding):

const text = await got('https://httpbin.org/anything').text();
console.log(typeof text);
//=> 'string'

语义上等价于 resolveBodyOnly: true + responseType: 'text'。

3.4 三者可并行调用

由于 .json() / .buffer() / .text() 返回的是派生 Promise,可以在同一个请求上并行调用:

const responsePromise = got('https://httpbin.org/anything');
const bufferPromise = responsePromise.buffer();
const jsonPromise = responsePromise.json();

const [response, buffer, json] = await Promise.all([
	responsePromise,
	bufferPromise,
	jsonPromise,
]);
// `response` —— 完整的 Got Response 对象
// `buffer`  —— Uint8Array 原始字节
// `json`    —— 解析后的对象

这一用法在官方文档 documentation/2-options.md#responsetype 中也有示例,测试 test/promise.ts 则验证了三个快捷方法在 resolveBodyOnly 为 true / false 时都能正确处理被钩子(hook)抑制的错误。

3.5 源码原理:shortcut() 与 parseBody()

三个快捷方法共享同一个内部函数 shortcut()(source/as-promise/index.ts):

  1. 先 await 原 Promise,等待下载结束、拿到 Response;
  2. 若响应是压缩体且未解压,globalResponse 会被刷新为最新响应;
  3. responseType === 'text' 时用 decodeUint8Array(rawBody, encoding) 解码字符串;
  4. 其余情况调用 parseBody(globalResponse, responseType, options.parseJson, options.encoding)。

parseBody 定义在 source/core/response.ts:'text' 走文本解码,'json' 走 parseJson(默认 JSON.parse,可自定义,见 documentation/2-options.md#parsejson),'buffer' 直接返回原始 Uint8Array;解析失败会抛出带 response 属性的 ParseError(错误码 ERR_BODY_PARSE_FAILURE),并尽量保留原始响应文本以便排查。

四、事件系统:on / once / off

Promise 上的事件与 Stream API 完全一致,底层通过 proxyEvents() 将 Request(一个 Duplex 流)的事件转发到 Promise 内部的一个 EventEmitter 上(source/core/utils/proxy-events.ts)。

被转发的核心事件列表见 source/as-promise/index.ts:

const proxiedRequestEvents = [
	'request',
	'response',
	'redirect',
	'uploadProgress',
	'downloadProgress',
];

4.1 promise.on(event, handler)

为事件注册监听器。事件包括:

  • request:拿到底层 Node.js http.ClientRequest,可用于直接 destroy() 请求。
  • response:收到最终响应的 Response 对象(测试 test/promise.ts 验证了该事件中 response.statusCode、response.ip 等字段可用)。
  • redirect:重定向时触发,携带下一跳的 Options 与当前 IncomingMessage。
  • uploadProgress / downloadProgress:上传/下载进度。

进度对象 Progress 的结构定义在 source/core/index.ts:

type Progress = {
	percent: number;      // 0 ~ 1
	transferred: number;  // 已传输字节数
	total?: number;       // 总字节数;缺少 content-length 时为 undefined
};

percent 在 total 未知时为 undefined 或按已传输量计算,实战中判断 typeof progress.percent === 'number' 再渲染进度条即可。

4.2 promise.once(event, handler)

注册一次性监听器,触发一次后自动移除。

4.3 promise.off(event, handler)

移除之前通过 promise.on 注册的监听器。官方文档给出的完整示例(上传进度监听 + 定时移除):

import {createReadStream} from 'node:fs';
import got from 'got';

const ongoingRequestPromise = got.post(uploadUrl, {
	body: createReadStream('sample.txt')
});

const eventListener = progress => {
	console.log(progress);
};

ongoingRequestPromise.on('uploadProgress', eventListener);

setTimeout(() => {
	ongoingRequestPromise.off('uploadProgress', eventListener);
}, 500);

await ongoingRequestPromise;

on / once / off 三个方法的实现见 source/as-promise/index.ts:它们直接委托给内部 emitter(一个 EventEmitter),并返回 this 以支持链式调用。类型层面,RequestPromise 交叉了 RequestEvents(见 source/as-promise/types.ts 与 source/core/index.ts),因此 TypeScript 会对 on('uploadProgress', ...) 的回调参数类型做完整推导。

4.4 上传进度进阶:chunk-data

对于 Node.js 流类型的 body,Got 无法自动计算精细进度(非流 body 如 string/Uint8Array/json/form 是自动支持粒度进度的,见 documentation/3-streams.md#streamuploadprogress)。官方推荐配合 chunk-data 包手动分块:

import fs from 'node:fs';
import got from 'got';
import {chunkFromAsync} from 'chunk-data';

const filePath = 'large-file.bin';
const stream = fs.createReadStream(filePath);
const size = fs.statSync(filePath).size;

await got.post('https://httpbin.org/anything', {
	body: chunkFromAsync(stream, 65_536),
	headers: {
		'content-length': size
	}
})
.on('uploadProgress', progress => {
	console.log(progress);
});

源码注释(source/core/index.ts)印证了这一点:不分块时 string/Uint8Array/TypedArray 的 body 会一次性写入,导致 uploadProgress 只在 0% 和 100% 各触发一次。

五、请求取消:signal + AbortController

Promise API 的请求取消通过 signal 选项与 AbortController 实现(见 documentation/2-options.md#signal):

import got from 'got';

const abortController = new AbortController();

const request = got('https://httpbin.org/anything', {
	signal: abortController.signal
});

setTimeout(() => {
	abortController.abort();
}, 100);

abort() 后,该 Promise 会以 AbortError(错误码 ERR_ABORTED)被 reject。测试 test/promise.ts 专门验证了“在文件流 body 尚未打开时就调用 promise.json(),随后 abort()”的场景:原 Promise 与 .json() 派生 Promise 都会以 AbortError 拒绝,说明取消信号在派生 Promise 之间正确传递。对应的错误类型定义见 source/core/errors.ts。

六、底层运行机制:asPromise() 做了什么

理解 Promise API 的健壮性来源,可以读一读它的核心实现 source/as-promise/index.ts。整体流程如下:

  1. 创建内部 EventEmitter,用于承载被转发过来的请求事件(request / response / redirect / uploadProgress / downloadProgress)。
  2. 构造 Request 并标记 _noPipe = true:告诉底层流“本次请求不使用管道(pipe)模式”,这也是 Promise 模式与流模式在 Request 层面的分叉点。
  3. 监听 response 事件并异步解析 body:
    • 处理压缩编码(gzip、x-gzip、deflate、br、zstd)且 decompress: false 的情况,直接把 rawBody 赋给 body;
    • 无 body 响应(HEAD、204、205、304)跳过解析;
    • 调用 parseBody(response, options.responseType, options.parseJson, options.encoding) 按类型解析;
    • 解析失败时先尝试保留原始文本(decodeUint8Array),再按需抛出 ParseError 或 HTTPError。
  4. 执行 afterResponse 钩子链:钩子可以返回新 Options 实现响应改写或触发 RetryError 重试(详见 documentation/9-hooks.md)。
  5. 判断 response.ok(isResponseOk 定义在 source/core/response.ts:2xx 与 304 视为成功,3xx 在未跟随重定向时也算成功):不 OK 且默认开启 throwHttpErrors 时抛 HTTPError。
  6. settle Promise:resolveBodyOnly 为真时 resolve response.body,否则 resolve 完整 Response 对象(见 source/as-promise/index.ts)。
  7. 重试协调:监听 retry 事件。若 Promise 已 settle 则放弃重试(防止“成功响应后迟到的 ECONNRESET”错误触发重试的竞态,见 source/as-promise/index.ts);若 body 是已消费的流(isNonReplayableBody)则改为报错“Cannot retry with consumed body stream”而非重试。

6.1 与 Stream API 的关系

Promise 与流共享同一个 Request 内核:

  • got(url, options) → 内部走 asPromise(request) 返回 RequestPromise;
  • got.stream(url, options) → 直接返回 Request(一个 Duplex 流)实例(见 source/create.ts)。

两者的选择建议:需要逐步消费大响应、pipe 到文件/响应流时用 Stream API;需要“等完整结果 + 类型化解析 + 进度监听”时用 Promise API。官方比较表(readme.md)也把 “Promise API” 与 “Stream API” 并列为其核心卖点。

七、实战注意事项

  1. 默认会重试:Got 默认对失败请求重试(见 documentation/7-retry.md)。若不需要,设置 retry: {limit: 0}。在 Promise 模式下重试是自动的,无需像流模式那样手动处理 retry 事件。
  2. 非 2xx/3xx 状态码默认抛错:throwHttpErrors 默认为 true(documentation/2-options.md#throwhttperrors)。做资源探测时可置为 false,此时错误状态码会 resolve 而不是 reject;测试 test/promise.ts 验证了 throwHttpErrors: false 时 .json() 不会因 400 而失败。
  3. 错误对象带完整元数据:RequestError / HTTPError / ParseError / RetryError 等均携带 response、request、timings 等字段(见 documentation/8-errors.md),便于排查与上报。
  4. json 选项与 .json() 是两回事:json 选项只影响请求体序列化;响应体的 JSON 解析必须用 .json() 或 responseType: 'json'(documentation/2-options.md#json 中特别标注了这一点)。
  5. 派生 Promise 的错误传播:.json() / .buffer() / .text() 返回的新 Promise 与原 Promise 共享错误语义。测试 test/promise.ts 验证了四个 Promise(原 Promise + 三个快捷方法)会一致地以 HTTPError 拒绝。
  6. TypeScript 友好:RequestPromise<T> 是 Promise<T> & RequestPromiseShape<T>(见 source/as-promise/types.ts),got<T>()、.json<T>() 均可泛型推导,配合 documentation/typescript.md 可享受完整的类型提示。

八、小结

Got 的 Promise API 以“一个 Promise,多种取数姿势”为核心设计:await got(url) 拿完整响应,.json() / .buffer() / .text() 按需取解析体,.on() / .once() / .off() 挂载流式事件,signal 实现标准取消。其实现(source/as-promise/index.ts)在底层 Request 流之上优雅地叠加了 body 解析、钩子链、重试与错误汇总逻辑,并被 test/promise.ts 中 612 行测试覆盖。上手时只需记住:URL 放第一位,选项放第二位,然后用 .json() 或事件接口按需取用。

登录后查看全文
got