请求工具 Request

自己在实际项目开发中，将常用的配置扩展到 uni.request、uni.uploadFile 中，方便使用。

兼容性

• 兼容：✅
• 不兼容：❌
• 未知：❔

H5	安卓	苹果	微信	支付宝	百度	抖音	QQ	快手	飞书	京东
✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅

小红书	鸿蒙	360	华为快应用	快应用联盟
✅	❔	❔	❔	❔

插件市场地址

DCloud 插件市场地址

使用示例

<script>
    // 导入工具
    import { PureHttp } from "@/uni_modules/pure-http";

    // 创建实例
    const http = new PureRequest({
        // 配置项
        // ...
    });

    // 创建接口函数
    function apiGetUserInfo(config = {
        // 参数
        data: {}
    }) {
        return http.get("/api/user/info");
    }

    // 使用接口函数
    // 返回 Promise
    apiGetUserInfo().then((res) => {
        // 接口请求成功
        console.log(res);
    }).catch((err) => {
        // 接口请求失败
        console.error(err);
    });

    // 返回 TaskId
    const taskId = apiGetUserInfo({
        // 参数
        data: {},
        // 成功
        success: (data, config) => {
            console.log(data, config);
        },
        // 异常
        error: (err, config) => {
            console.error(err, config);
        },
        // 未请求通
        fail: (response, config) => {
            console.error(response, config);
        },
        // 完成
        complete: (res) => {
            console.log(response, config);
        }
    });
</script>

配置项

字段名	说明	类型	默认值	可选值	版本
baseURL	接口基准前缀(一般为接口域名地址)	String	""	-	+1.0.0
url	接口地址，可以是绝对路径或者相对路径，如果是相对路径，最终会和 baseURL 合并成一个完整的 URL	String	""	-	+1.0.0
data	请求的参数	Object	{}	-	+1.0.0
header	请求的 header, header 中不能设置 Referer	Object	{}	-	+1.0.0
method	请求类型，大写	String	GET	POST、PUT、DELETE、CONNECT、HEAD、OPTIONS、TRACE、UPLOAD（扩展的）	+1.0.0
timeout	超时时间，单位毫秒	Number	30000	-	+1.0.0
dataType	我要发送的数据类型，如果设为 json, 会对返回的数据进行一次 JSON.parse, 非 json 不会进行 JSON.parse	String	json	-	+1.0.0
responseType	响应的数据类型	String	text	arraybuffer	+1.0.0
sslVerify	是否验证 ssl 证书	Boolean	true	false	+1.0.0
withCredentials	跨域请求时是否携带凭证（cookies）	Boolean	false	true	+1.0.0
firstIpv4	DNS 解析时是否优先使用 ipv4	Boolean	false	true	+1.0.0
enableHttp2	是否开启 http2	Boolean	false	true	+1.0.0
enableQuic	是否开启 quic	Boolean	false	true	+1.0.0
enableCache	是否开启 cache	Boolean	false	true	+1.0.0
enableHttpDNS	是否开启 HttpDNS 服务	Boolean	false	true	+1.0.0
httpDNSServiceId	HttpDNS 服务商 Id	String	""	-	+1.0.0
enableChunked	是否开启 transfer-encoding chunked	Boolean	false	true	+1.0.0
forceCellularNetwork	是否在 wifi 下使用移动网络发送请求	Boolean	false	true	+1.0.0
enableCookie	开启后可在 headers 中编辑 cookie	Boolean	false	true	+1.0.0
cloudCache	是否开启云加速	Boolean	false	true	+1.0.0
defer	控制当前请求是否延时至首屏内容渲染后发送	Boolean	false	true	+1.0.0
files	需要上传的文件列表。使用 files 时，filePath 和 name 不生效	Array[File]	null	-	+1.0.0
fileType	文件类型	String	image	video、audio	+1.0.0
file	要上传的文件对象	File	null	-	+1.0.0
filePath	要上传文件资源的路径	String	null	-	+1.0.0
name	文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容	String	file	-	+1.0.0
formData	HTTP 请求中其他额外的 form data	Object	{}	-	+1.0.0
success	请求成功的回调函数，详细说明	Function	null	-	+1.0.0
error	请求异常的回调函数，详细说明	Function	null	-	+1.0.0
fail	请求失败的回调函数，详细说明	Function	null	-	+1.0.0
complete	请求完成的回调函数，详细说明	Function	""	-	+1.0.0
requestTokenKey	请求时 header 中携带的鉴权凭证名称	String	Authorization	-	+1.0.0
responseTokenKey	接口返回 header 数据中携带的鉴权凭证名称	String	Authorization	-	+1.0.0
storageTokenKey	存储在本地的鉴权凭证名称	String	Authorization	-	+1.0.0
requestRefreshTokenKey	请求时 header 中携带的更新鉴权凭证名称	String	refresh_token	-	+1.0.0
responseRefreshTokenKey	接口返回 header 数据中携带的更新鉴权凭证名称	String	refresh_token	-	+1.0.0
dataStatusKey	数据中表示状态码的字段名称	String	code	-	+1.0.0
dataStatusTextKey	数据中表示状态文本的字段名称	String	errMsg	-	+1.0.0
dataSuccessStatusCode	数据中表示成功状态的状态码	[Number, String]	0	-	+1.0.0
requestFailStatusCode	自定义的表示请求失败的状态码	[Number, String]	-1	-	+1.0.0
before	请求前的处理函数，详细说明	Function	null	-	+1.0.0
after	请求后的处理函数，详细说明	Function	null	-	+1.0.0
codeFunctions	状态码处理函数，详细说明	Object{Function}	{}	-	+1.0.0
showLoading	是否显示 loading	Boolean	true	false	+1.0.0
loadingTime	请求超过此值设置的毫秒数后才会显示，设置为 0 会在请求后立即显示	Number	800	-	+1.0.0
loadingText	提示内容	String	""	-	+1.0.0
loadingMask	是否显示透明蒙层，防止触摸穿透	Boolean	true	false	+1.0.0
loadingShowFunction	自定义显示 loading 的函数，参数为请求配置(config)	Function	null	-	+1.0.0
loadingHideFunction	自定义隐藏 loading 的函数，参数为请求配置(config)	Function	null	-	+1.0.0
showSuccess	是否显示 success 提示	Boolean	false	true	+1.0.0
successText	提示内容	String	""	-	+1.0.0
successIcon	图标	String	none	success	+1.0.0
successImage	自定义图标的本地路径	String	""	-	+1.0.0
successMask	是否显示透明蒙层，防止触摸穿透	Boolean	true	false	+1.0.0
successDuration	提示的持续时间，单位毫秒	Number	2500	-	+1.0.0
successPositon	提示的显示位置，填写有效值后只有 successText 属性生效	String	""	top、center、bottom	+1.0.0
successEndCallback	提示显示结束后的回调，参数为接口返回的数据和请求配置(config)	Function	null	-	+1.0.0
successShowFunction	自定义显示提示的函数，参数为接口返回的数据和请求配置(config)	Function	null	-	+1.0.0
showError	是否显示 error 提示	Boolean	false	true	+1.0.0
errorText	提示内容	String	""	-	+1.0.0
errorIcon	图标	String	none	erro	+1.0.0
errorImage	自定义图标的本地路径	String	""	-	+1.0.0
errorMask	是否显示透明蒙层，防止触摸穿透	Boolean	true	false	+1.0.0
errorDuration	提示的持续时间，单位毫秒	Number	2500	-	+1.0.0
errorPositon	提示的显示位置，填写有效值后只有 errorText 属性生效	String	""	top、center、bottom	+1.0.0
errorEndCallback	提示显示结束后的回调，参数为错误信息对象和请求配置(config)	Function	null	-	+1.0.0
errorShowFunction	自定义显示提示的函数。参数为错误信息对象和请求配置(config)	Function	null	-	+1.0.0
showFail	是否显示 fail 提示	Boolean	false	true	+1.0.0
failText	提示内容	String	""	-	+1.0.0
failIcon	图标	String	none	fail	+1.0.0
failImage	自定义图标的本地路径	String	""	-	+1.0.0
failMask	是否显示透明蒙层，防止触摸穿透	Boolean	true	false	+1.0.0
failDuration	提示的持续时间，单位毫秒	Number	2500	-	+1.0.0
failPositon	提示的显示位置，填写有效值后只有 errorText 属性生效	String	""	top、center、bottom	+1.0.0
failEndCallback	提示显示结束后的回调，参数为错误信息对象和请求配置(config)	Function	null	-	+1.0.0
failShowFunction	自定义显示提示的函数。参数为错误信息对象和请求配置(config)	Function	null	-	+1.0.0
beforeFalseCode	中断请求时的自定义状态码	[Number, String]	-20	-	+1.0.0
beforeFalseText	中断请求时的自定义状态文本	[Number, String]	请求被拦截了	-	+1.0.0
afterFalseCode	中断请求时的自定义状态码	[Number, String]	-40	-	+1.0.0
afterFalseText	中断请求时的自定义状态文本	[Number, String]	响应被拦截了	-	+1.0.0

success()

• 请求成功的回调函数。
• 请求成功表示 http statusCode 为 200，且数据状态码等于 dataSuccessStatusCode。

参数

• data: response.data 请求返回的数据。
• config: 本次请求的配置。

error()

• 请求异常的回调函数。
• 请求异常表示 http statusCode 不为 200，或者数据状态码不等于 dataSuccessStatusCode。

参数

• error: 本次请求的错误信息。
  • 如果是 http 状态码异常，则 error 为包含错误码和错误信息的对象。
  • 如果是数据状态码异常，则 error 为接口返回的数据。
• config: 本次请求的配置。

fail()

• 请求失败的回调函数。
• 请求失败包括: 网络不通、请求被强行中断、请求超时、找不到域名、ssl握手失败等。

参数

• response: 请求返回的 response 对象。
• config: 本次请求的配置。

complete()

• 请求完成的回调函数，无论成功还是失败都会执行。

参数

• response: 请求返回的 response 对象。
• config: 本次请求的配置。

before()

• 请求前的处理函数，该函数如果返回 true 则继续执行请求，否则请求不会执行并返回 Promise.reject(error)，error 为一个包含错误码和错误信息的对象。

参数

• config: 本次请求的配置。

after()

• 请求后的处理函数，该函数会在请求完成后首先调用，无论成功还是失败都会执行。
• 该函数返回 true 则表示继续执行后续逻辑，否则后续逻辑不会执行并返回 Promise.reject(error)，error 为一个包含错误码和错误信息的对象。

参数

• response: 请求返回的 response 对象。
• config: 本次请求的配置。

codeFunctions

• 状态码处理函数，该函数会在 after() 函数之后调用。
• codeFunctions 是一个对象，键为状态码，值为处理函数，例如：

codeFunctions: {
    // 假如状态码为 1000 时表示登录过期
    1000: (response, config) {
        // 返回 true 表示继续执行后续逻辑
        // 提示：只有返回 ture 时才会继续执行后续逻辑，即使时非严谨的等同于 `true` 的数据，如 1、{}、[] 等也不会认为是 true。
        // return true;
        // return {} // 非严谨的等同于 true 的数据，也会终止后续逻辑的执行
        // return [] // 非严谨的等同于 true 的数据，也会终止后续逻辑的执行
        // return 1 // 非严谨的等同于 true 的数据，也会终止后续逻辑的执行

        // 终止后续逻辑的执行，并返回错误对象
        return {
            code: 1000,
            errMsg: "登录过期"
        }
    }
}

• 处理函数的参数为：
  • response: 请求返回的 response 对象。
  • config: 本次请求的配置。
• 该函数返回 true 则表示继续执行后续逻辑，否则后续逻辑不会执行并返回 Promise.reject(error)，error 对应处理函数的返回值。

方法列表

方法名	描述	参数	返回值
get	GET 请求	config	Promise、TaskId
post	POST 请求	config	Promise、TaskId
upload	UPLOAD 请求	config	Promise、TaskId
delete	DELETE 请求	config	Promise、TaskId
connect	CONNECT 请求	config	Promise、TaskId
head	HEAD 请求	config	Promise、TaskId
options	OPTIONS 请求	config	Promise、TaskId
trace	TRACE 请求	config	Promise、TaskId
http	请求	config	Promise、TaskId
setConfig	设置配置	config	-
aborts	中断实例下的所有请求	-	-

返回值

• get、post、put、delete、head、options、trace、http 的返回值有两种。
• 如果 config 中配置了 success、error、fail、complete 中的任意一个函数，则返回 TaskId，否则返回 Promise。