@just4/request
提供封装了 HTTP 请求流程的 Promise 化接口。
特性
- 具备 Promise 化的接口，并支持中断请求。
- 带有 TypeScript 类型声明。
- 支持浏览器和微信小程序两种运行环境，并提供了一致的外部接口。
- 在浏览器环境下：
- 封装了 XMLHTTPRequest 对象创建、请求发起、请求响应的全流程。
- 支持发送常用的数据类型：文本、对象、FormData、Blob 和 ArrayBuffer。
- 支持把数据序列化为
application/json或application/x-www-form-urlencoded的请求体。 - 根据选项设置把响应内容解析为 JSON、XML、文本、Blob 或 ArrayBuffer。
- 支持文件上传和下载场景下的进度响应（
onDownloadProgress、onUploadProgress）。 - 支持 PC 和移动端所有主流浏览器（其中 IE 浏览器的最低兼容版本是 9）。
- 在 IE 9 中，符合特定条件的情况下，通过 XDomainRequest 发起跨域请求。
- 在微信小程序环境下：
- 基于 wx.request 进行封装。
- 支持发送的数据类型包括：文本、对象和 ArrayBuffer。
- 根据选项设置把响应内容解析为 JSON、文本或 ArrayBuffer。
安装
npm i @just4/request调用
适配不同运行环境
浏览器端
import { Request } from '@just4/request';
import { xhrAdapter } from '@just4/request/adapter/xhr';
const xhrRequest = new Request(xhrAdapter);微信小程序端
需先安装 miniprogram-api-typings。
import { Request } from '@just4/request';
import { wxRequestAdapter } from '@just4/request/adapter/xhr';
// 用于微信小程序端
const wxRequest = new Request(wxRequestAdapter);发送请求
创建 Request 类的实例之后，就可以调用相关方法：
const result = await xhrRequest.send(url, {
// 选项说明见 API 文档
});
res.data; // data 是响应数据
res.options; // options 是请求选项
res.requestWith; // requestWith 是所使用的适配器的标识请求选项的合并
实例化 Request 实例时可以传入基础选项。调用 send 方法时，传入的选项将与基础选项合并。合并后的选项才是请求时使用的选项。
const xhrRequest = new Request(xhrAdapter, {
responseType: 'json'
preventCaching: false
});
// 合并后的选项为 { responseType: 'json', preventCaching: true }
xhrRequest.send(url, {
preventCaching: true
});GET 请求
// 以下两种调用方法，发送的请求是一样的
await xhrRequest.send('/detail?id=12345');
await xhrRequest.send('/detail', {
params: { id: '12345' }
});POST 请求
把 method 选项的值设为 POST，就可以发送 POST 请求。
await xhrRequest.send('/login', {
method: 'POST',
data: {
username: 'user',
password: 'qwer123'
}
});如果 POST 请求的部分数据是以 URL 参数的形式传输，仍然可以放到 params 选项中：
await xhrRequest.send('/login', {
method: 'POST',
params: {
from: 'promotion'
},
data: {
username: 'user',
password: 'qwer123'
}
});默认情况下，POST 请求的数据是以 application/x-www-form-urlencoded 编码发送的。如果需要发送 application/json 编码的数据，可以把 requestType 设置为 json。
await xhrRequest.send('/login', {
method: 'POST',
requestType: 'json',
params: {
from: 'promotion'
},
data: {
username: 'user',
password: 'qwer123'
}
});防止缓存
设置 preventCaching 选项为 true 后，send 方法会在请求的 URL 后拼接时间戳参数（任何请求方式都有效）。
// 实际请求的地址类似于 /detail?id=12345&_=1672712809951
await xhrRequest.send('/detail', {
params: { id: '12345' },
preventCaching: true
});请求超时
可以通过 timeout 指定请求的超时时间（毫秒）。如果请求超时，将会返回拒绝状态的 promise 实例。
import { RequestErrorType } from '@just4/request';
try {
await xhrRequeset.send('/login', {
method: 'post',
data: {
username: 'user',
password: 'qwer123'
},
timeout: 8000
});
} catch (e) {
if (e.type === RequestErrorType.TIMEOUT) {
// 请求超时
}
}取消请求
先通过 receiveTaskId 把请求的 id 记录下来，通过 cancel 方法取消请求。如果请求在完成前被取消，将会返回拒绝状态的 promise 实例。
let taskId = 0;
setTimeout(() => {
cancel(requestId);
}, 5000);
try {
await xhrRequest.send('/login', {
method: 'POST',
data: {
username: 'user',
password: 'qwer123'
},
receiveTaskId(id) {
taskId = id;
}
});
} catch (e) {
if (e.type === RequestErrorType.ABORT) {
// 请求被取消
}
}API 文档
Changelog
v0.6.0
- 为保证调用上的灵活性，
@just4/request/index不再导出适配器。 -
Request类的send、get和post都允许不传options参数。
v0.5.0
- 请求选项新增
extra字段，可用于传入自定义选项。
v0.4.0
- 升级依赖包版本并对应调整相关 API 的调用。