# @billjs/request 中文文档

规范地址：https://npmcn.com/package/%40billjs/request/

版本：1\.0\.1
npm 元数据更新时间：2022-04-04T18:49:50.151Z
中文译文更新时间：2026-11-08T02:32:48.428Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40billjs/request
原文对照：https://npmcn.com/package/%40billjs/request/?lang=original
项目主页：https://github.com/billjs/request#readme
源码仓库：https://github.com/billjs/request

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：56 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2018-12-16T02:17:39.071Z
- 最新版本发布：2019-01-03T02:58:26.389Z
- 近 30 天下载量：2747（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

一个简单而轻巧的HTTP请求库由TypeScript为浏览器提供.

## 安装

```sh
npm install @billjs/request
```

也可以使用：`pnpm add @billjs/request`、`yarn add @billjs/request`、`bun add @billjs/request`

## README

# 请求 [![Travis-ci Status](https://api.travis-ci.org/billjs/request.svg?branch=master)](https://travis-ci.org/billjs/request) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/billjs/request/blob/master/LICENSE) ![typescript | javascript | node.js](https://img.shields.io/badge/language-typescript%20%7C%20javascript%20%7C%20node.js-yellow.svg) [![Npm Version](https://img.shields.io/npm/v/@billjs/request.svg)](https://www.npmjs.com/package/@billjs/request) [![NPM Download](https://img.shields.io/npm/dm/@billjs/request.svg)](https://npmcharts.com/compare/@billjs/request?minimal=true)

一个简单而轻巧的HTTP请求库由TypeScript为浏览器提供. 图书馆更喜欢 `window.fetch` API 和使用 `XMLHttpRequest` 没有支持.

## 安装

安装使用 `npm install` 命令 :

```shell
npm install -S @billjs/request
```

## 概览

-   [获取](https://npmcn.com/package/%40billjs/request/#readme-fetch)
-   [起来](https://npmcn.com/package/%40billjs/request/#readme-get)
-   [头](https://npmcn.com/package/%40billjs/request/#readme-head)
-   [员额](https://npmcn.com/package/%40billjs/request/#readme-post)
-   [设置](https://npmcn.com/package/%40billjs/request/#readme-put)
-   [补丁](https://npmcn.com/package/%40billjs/request/#readme-patch)
-   [三角形](https://npmcn.com/package/%40billjs/request/#readme-del)
-   [选项](https://npmcn.com/package/%40billjs/request/#readme-options)
-   [上传](https://npmcn.com/package/%40billjs/request/#readme-upload)
-   [抓取成功](https://npmcn.com/package/%40billjs/request/#readme-catchsuccess)
-   [抓取错误](https://npmcn.com/package/%40billjs/request/#readme-catcherror)
-   [抓取完成](https://npmcn.com/package/%40billjs/request/#readme-catchcomplete)
-   [解析回复](https://npmcn.com/package/%40billjs/request/#readme-parseresponse)

## API 密码

### 获取

HTTP请求. 这是一个基本的请求方法,你可以使用它发送任何方法的请求. 这个 `success` 当请求成功时将触发事件,这意味着 [抓取成功](https://npmcn.com/package/%40billjs/request/#readme-catchsuccess) 将召入. 这个 `error` 当请求失败时将触发事件,这意味着 [抓取错误](https://npmcn.com/package/%40billjs/request/#readme-catcherror) 将召入. 无论是成功还是失败的请求 `complete` 全部触发,这意味着 [抓取完成](https://npmcn.com/package/%40billjs/request/#readme-catchcomplete) 都叫来.

-   **url 密码** (单位:千美元)`string`请求url
-   _**\[数据\]**_ (单位:千美元)`any` `optional`要求数据,例如: `text` `JSON` `FormData`等 (中文(简体) ).
-   _**\[可选**_ (单位:千美元)[请求选项](https://npmcn.com/package/%40billjs/request/#readme-requestoptions) `optional`额外备选办法,例如 `headers` 财务报告和审定财务报表 `type`等 (中文(简体) ).
-   **返回时** (单位:千美元)`Promise`它返回一个 `Promise`,您可以使用 `then` 财务报告和审定财务报表 `catch` 方法 `Promise` 或者说 `async/await` 解决结果.

使用 `then` 财务报告和审定财务报表 `catch` 方法 `Promise` 解决结果.

```typescript
fetch('/api/user/1234', null, { method: 'GET' })
  .then(data => console.log(data))
  .catch(err => console.log(err));
```

使用 `async/await` 解决结果.

```typescript
async function getUser(uid: string) {
  try {
    const user = await fetch('/api/user/1234', null, { method: 'GET' });
    console.log(user);
  } catch (err) {
    console.error(err);
  }
}
```

### 起来

获取数据. 会用到的 `GET` 发送请求的方法。 此是自相能请.

-   **url 密码** (单位:千美元)`string`) 获取请求url
-   _**\[数据\]**_ (单位:千美元)`string | object | null`) 查询参数。 它可以是字符串,也可以是对象.
-   _**\[可选**_ (单位:千美元)[请求选项](https://npmcn.com/package/%40billjs/request/#readme-requestoptions) `optional`额外备选办法,例如 `headers` 财务报告和审定财务报表 `type`等 (中文(简体) ).
-   **返回时** (单位:千美元)`Promise`(中文(简体) )

```typescript
get('/api/user/1234')
  .then(user => console.log(user))
  .catch(err => console.log(err));
```

### 头

这个 `HEAD` 方法请求与 `GET` 请求,但没有反应机构。 您可以用它来检查API是否正常工作 。 此是自相能请.

-   **url 密码** (单位:千美元)`string`) 头请求url
-   _**\[数据\]**_ (单位:千美元)`string | object | null`) 查询参数。 它可以是字符串,也可以是对象.
-   _**\[可选**_ (单位:千美元)[请求选项](https://npmcn.com/package/%40billjs/request/#readme-requestoptions) `optional`额外备选办法,例如 `headers` 财务报告和审定财务报表 `type`等 (中文(简体) ).
-   **返回时** (单位:千美元)`Promise`(中文(简体) )

```typescript
head('/api/user/1234').catch(err => console.log(err));
```

### 员额

为新资源提交数据 。 会用到的 `POST` 发送请求的方法。 这是非本能的要求.

-   **url 密码** (单位:千美元)`string`() 员额请求url
-   _**\[数据\]**_ (单位:千美元)`any`提交服务器的数据,可以是任何数据类型.
-   _**\[可选**_ (单位:千美元)[请求选项](https://npmcn.com/package/%40billjs/request/#readme-requestoptions) `optional`额外备选办法,例如 `headers` 财务报告和审定财务报表 `type`等 (中文(简体) ).
-   **返回时** (单位:千美元)`Promise`(中文(简体) )

```typescript
post('/api/user', { name: 'test', age: 32 })
  .then(id => console.log(id))
  .catch(err => console.log(err));
```

### 设置

更新数据以替换资源 。 会用到的 `PUT` 发送请求的方法。 此是自相能请.

-   **url 密码** (单位:千美元)`string`将请求 url
-   _**\[数据\]**_ (单位:千美元)`any`提交服务器的数据,可以是任何数据类型.
-   _**\[可选**_ (单位:千美元)[请求选项](https://npmcn.com/package/%40billjs/request/#readme-requestoptions) `optional`额外备选办法,例如 `headers` 财务报告和审定财务报表 `type`等 (中文(简体) ).
-   **返回时** (单位:千美元)`Promise`(中文(简体) )

```typescript
put('/api/user/1234', { name: 'test', age: 22 }).catch(err => console.log(err));
```

### 补丁

类似 `PUT` 请求,但仅限于本地修改。 会用到的 `PATCH` 发送请求的方法。 这是非本能的要求.

-   **url 密码** (单位:千美元)`string`) 补丁请求url
-   _**\[数据\]**_ (单位:千美元)`any`提交服务器的数据,可以是任何数据类型.
-   _**\[可选**_ (单位:千美元)[请求选项](https://npmcn.com/package/%40billjs/request/#readme-requestoptions) `optional`额外备选办法,例如 `headers` 财务报告和审定财务报表 `type`等 (中文(简体) ).
-   **返回时** (单位:千美元)`Promise`(中文(简体) )

```typescript
patch('/api/user/1234', { age: 28 })
  .then(user => console.log(user))
  .catch(err => console.log(err));
```

### 三角形

删除数据。 会用到的 `DELETE` 发送请求的方法。 此是自相能请.

-   **url 密码** (单位:千美元)`string`删除请求url
-   _**\[数据\]**_ (单位:千美元)`any`提交服务器的数据,可以是任何数据类型.
-   _**\[可选**_ (单位:千美元)[请求选项](https://npmcn.com/package/%40billjs/request/#readme-requestoptions) `optional`额外备选办法,例如 `headers` 财务报告和审定财务报表 `type`等 (中文(简体) ).
-   **返回时** (单位:千美元)`Promise`(中文(简体) )

```typescript
del('/api/user/1234')
  .then(success => console.log(success))
  .catch(err => console.log(err));
```

### 选项

这个 `OPTIONS` 请求,常用于跨域探索。 此是自相能请.

-   **url 密码** (单位:千美元)`string`) 选项请求url
-   _**\[可选**_ (单位:千美元)[请求选项](https://npmcn.com/package/%40billjs/request/#readme-requestoptions) `optional`额外备选办法,例如 `headers` 财务报告和审定财务报表 `type`等 (中文(简体) ).
-   **返回时** (单位:千美元)`Promise`(中文(简体) )

```typescript
options('/api/user')
  .then(res => console.log(res))
  .catch(err => console.log(err));
```

### 上传

上传窗体数据,例如文件等. 会用到的 `Content-Type` 联 合 国 `multipart/form-data` 上传窗体数据.

-   **url 密码** (单位:千美元)`string`)上传url
-   _**\[数据\]**_ (单位:千美元)`FormData`() 窗体数据
-   _**\[可选**_ (单位:千美元)[请求选项](https://npmcn.com/package/%40billjs/request/#readme-requestoptions) `optional`额外备选办法,例如 `headers` 财务报告和审定财务报表 `type`等 (中文(简体) ).
-   **返回时** (单位:千美元)`Promise`(中文(简体) )

```typescript
const formData = new FormData();
formData.append('image', blob);
upload('/api/upload/image', formData)
  .then(data => console.log(data))
  .catch(err => console.log(err));
```

### 抓取成功

环球捕捉所有成功的请求, 然后你可以做一些事情.

-   **页:1** (单位:千美元)`(data: any, req: Request) => void`)回调函数。 任何成功的请求都会称为此回调功能. 这个 `req` 参数是一个 [请求](https://npmcn.com/package/%40billjs/request/#readme-request) 举个例子.

```typescript
catchSuccess((data, req) => {
  console.log(data);
});
```

### 抓取错误

Global 捕获所有失败的重排, 然后您就可以做一些事情, 例如显示错误消息提示 .

-   **页:1** (单位:千美元)`(err: RequestError, req: Request) => void`)回调函数。 任何失败的请求都将调用此调用函数 。 这个 `err` 参数是一个 [请求错误](https://npmcn.com/package/%40billjs/request/#readme-requesterror) 举个例子.

```typescript
catchError((err, req) => {
  // show an error message
  Message.error(err.message);
});
```

### 抓取完成

Global 捕捉所有请求, 无论是成功还是失败, 那么您都可以做一些事情 .

-   **页:1** (单位:千美元)`(err: RequestError | null, data: any, req: Request) => void`)回调函数。 任何请求都会调用此调用函数 .

```typescript
catchComplete((err, data, req) => {
  console.log(err, data);
});
```

### 解析回复

全球定制的 HTTP 响应数据解析器, 它只对 `json` 数据类型. 您可以指定定制的解析器来解析针对自己的响应数据 。 但你必须返回正确的响应数据 由 `ResponseData` 结构. 如果您的服务器响应数据结构与 `ResponseData`,不需要指定剖析.

-   **页:1** (单位:千美元)`ParseFunction`解析器 `result` 参数是您的服务器响应数据。 这个 `return` 是一个 [反应数据](https://npmcn.com/package/%40billjs/request/#readme-responsedata) 举个例子.

如果你有自己的响应数据结构,你可以做到这一点. 例如:

```typescript
parseResponse(result => {
  return {
    success: result.success,
    statusCode: 200,
    errorCode: result.error_code,
    errorMessage: result.error_msg,
    errorStack: result.error_stack ? result.error_stack : null,
    data: result.data,
  };
});
```

## 请求

HTTP 请求的类, 命名为 `Request`它执行请求的所有逻辑细节. 大多数时候,你不需要创建 `Request` 实例以发送 HTTP 请求,只需调用上述快捷键.

这样的建筑师宣言:

```typescript
constructor(url: string, data: any, options: RequestOptions);
```

-   **url 密码** (单位:千美元)`string`请求url
-   **数据** (单位:千美元)`any`要求数据,例如: `text` `JSON` `FormData`等 (中文(简体) ).
-   **选项** (单位:千美元)[请求选项](https://npmcn.com/package/%40billjs/request/#readme-requestoptions)额外备选办法,例如 `headers` 财务报告和审定财务报表 `type`等 (中文(简体) ).

## 请求选项

每个请求的选项, 您可以传递一些选项到 `Request` 为了你的案子.

选项列表 :

-   **方法** (单位:千美元)`RequestMethod`HTTP 请求方法,参见 [请求方法](https://npmcn.com/package/%40billjs/request/#readme-requestmethod)默认值 `GET`。 。 。 .
-   **页眉** (单位:千美元)`RequestHeaders`)定制的HTTP请求头. 例如{"X-CSRF-Token":"123"}. 这是关键值地图.
-   **类型** (单位:千美元)`RequestType`数据提交类型,见 [请求类型](https://npmcn.com/package/%40billjs/request/#readme-requesttype)默认值 `json`。 。 。 .
-   **数据类型** (单位:千美元)`RequestDataType`接受的答复数据类型,见 [请求数据类型](https://npmcn.com/package/%40billjs/request/#readme-requestdatatype)默认值 `json`。 。 。 .
-   **内容类型** (单位:千美元)`RequestContentType`(b) 请求 `Content-Type`,参见 [请求类型](https://npmcn.com/package/%40billjs/request/#readme-requestcontenttype)默认值 `application/json`。 。 。 .
-   **超时** (单位:千美元)`number`HTTP 请求超时, 默认 `0`,这意味着没有设置超时.
-   **使用XHR软件** (单位:千美元)`boolean`被强迫使用 XHR ()`XMLHttpRequest`) 默认 `false`,使用意愿 `window.fetch` API (英语). 在大多数情况下,我们建议您使用 `window.fetch` API (英语).
-   **全权证书** (单位:千美元)`boolean`您需要发送 `cookie` 证书? 如果来源相同,则默认为 `true`。否则,它就是 `false`,这意味着不发送 `cookie` 证书。 如果您需要发送 `cookie` 跨域证书,您需要将其指定为 `true`。 。 。 .
-   **剖析** (单位:千美元)`ParseFunction`)此请求的定制HTTP响应数据解析器. 如果没有指定,则将使用全局定制的解析器或默认解析器.
-   **进展情况报告** (单位:千美元)`(loaded: number, total: number) => void`HTTP 请求进度事件处理器 .

### 请求方法

HTTP 请求方法 : `GET`, (中文(简体) ), `HEAD`, (中文(简体) ), `POST`, (中文(简体) ), `PUT`, (中文(简体) ), `PATCH`, (中文(简体) ), `DELETE`, (中文(简体) ), `OPTIONS`。 。 。 . 此属性值是大小写不敏感, 意思是 `get` 等于 `GET`。 。 。 .

### 请求类型

数据提交类型: `json`, (中文(简体) ), `text`, (中文(简体) ), `urlencoded`, (中文(简体) ), `form`。 。 。 . 相应 `Content-Type` 请求头将按提交类型自动设置.

-   **乔森**由JSON提交,请求 `Content-Type` 实值 `application/json`。 。 。 .
-   **文本**: 通过 plainText 提交请求 `Content-Type` 实值 `text/plain`。 。 。 .
-   **urlen 编码**: 以 urlEncode 形式提交请求 `Content-Type` 实值 `application/x-www-form-urlencoded`。 。 。 .
-   **表单**: 通过表格Data提交请求 `Content-Type` 实值 `multipart/form-data`。 。 。 .

### 请求数据类型

接受的响应数据类型: `json`, (中文(简体) ), `text`。 。 。 . 相应 `Content-Type` 响应头将按数据类型设置.

-   **乔森**接受JSON的回应 `Content-Type` 实值 `application/json`。 。 。 .
-   **文本**: 由 plainText 编辑, 反应 `Content-Type` 实值 `text/plain`。 。 。 .

### 请求类型

请求 `Content-Type`默认值 `application/json`。 。 。 . 如果 `type` 中指定了与类型相对应的内容. 如果值是 `false`,这意味着没有设置 `Content-Type` 定制标题 。 例如,上传文件时,需要指定为 `false`。 。 。 .

## 请求错误

请求错误类, 它从错误延伸 . 添加 `status` 财务报告和审定财务报表 `code` 属性。 这个 `status` 属性为 HTTP 状态。 这个 `code` 属性是商务错误代码.

这样的建筑师宣言:

```typescript
constructor(status: number, code: string, msg: string, stack?: string | null);
```

## 反应数据

标准化响应数据结构.

-   **成功** (单位:千美元)`boolean`成败状况.
-   **状态代码** (单位:千美元)`number`)状态代码,它与HTTP状态相同.
-   **错误代码** (单位:千美元)`string` | `number`错误代码,当请求失败时.
-   **错误** (单位:千美元)`string` | `null`当请求失败时, 错误消息 。 如果请求成功,则 `null`。 。 。 .
-   **错误** (单位:千美元)`string` | `null`当请求失败时, 错误堆栈 。 仅限 `development` 模式,否则 `null`。 。 。 .
-   **数据** (单位:千美元)`any` | `null`反应数据,它是任何类型。 如果请求失败, 则 `null`。 。 。 .

但作为一名来电者,你只会得到 `data` 你不需要关心其他的事情.

## 许可证

[MIT 许可证](https://npmcn.com/package/%40billjs/request/LICENSE)

## 常见问题

### @billjs/request 是什么？

一个简单而轻巧的HTTP请求库由TypeScript为浏览器提供\.

### 如何安装 @billjs/request？

在项目目录运行 npm install @billjs/request，或使用 pnpm add / yarn add / bun add。

### @billjs/request 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @billjs/request 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @billjs/request 可以商用吗？

@billjs/request 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @billjs/request 的下载量有多少？

根据 npm 官方下载统计，@billjs/request 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,747 次，日均约 92 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @billjs/request 还在维护吗？

最新版本 1\.0\.1 发布于 2019/01/03（7 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/12/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。