更新记录

1.0.13（2024-04-24）

• 修复编译到web、app-ios平台时错误输出异常问题。
• 修复 useRetry 请求失败时没有抛出异常的问题。
• 优化部分逻辑以支持后续编译器版本迭代。

1.0.12（2024-04-13）

• 调整 abort 方法内部实现逻辑，以解决原来无法在请求拦截器中中断请求的问题。

1.0.11（2024-04-13）

• useInterceptor 拦截器实例新增 useResponseXhr 拦截原始响应内容方法。

  const interceptor = useInterceptor();
  interceptor
      .useResponseXhr((res: RequestSuccess<any>): any => {
          console.log('原始响应拦截', res);
          if (typeof res.data === 'object') {
              const data = res.data as UTSJSONObject;
              console.log(data.getAny('data'));
          }
          return res;
      })

平台兼容性

kux-request

kux-request 是一个基于 uni.request 的一个简洁高效的uts请求库，支持请求同步/异步拦截、请求重试、请求过滤等丰富功能，提供人性化的请求配置，旨在帮助uniapp x开发者专注业务开发，提升业务开发效率。

插件特色

• 请求同步拦截
• 请求过滤
• 请求缓存
• 批量请求
• 请求重试【基于指数退避算法】
• 中断请求
• 人性化的请求配置
• 组合式API

目录结构

基础

安装配置

本插件为完全的 uni_modules 插件，所以直接在 插件市场 搜索 kux-request 安装即可。

入门使用

请求库挂载方式可以自己灵活实现，下面以模块引用作为演示说明。

注意
由于目前uts不支持把插件库的类型导出给外部模块之间共享使用，所以在调用请求库具体 API 时还需要手动导入插件库的类型使用，示例：

import { RequestConfig } from '@/uni_modules/kux-request';

模块引用

• 创建 http 目录，位置如：/utils/http
  

  提示

  1.该目录一般存储请求库相关的文件，比如初始化文件。
  2.目录名称和创建位置可以自定义。

• 创建 /utils/http/index.uts ，并初始化

  import { useRequest, UseOptions } from '@/uni_modules/kux-request';
  
  export const http = useRequest({
      baseURL: '', // 这里填写自己的请求域名
  } as UseOptions);

• 调用示例，这里演示 页面直接引入使用 和 API调用 两种方式

  • 页面直接引入使用

    import { http } from '@/utils/http/index';
    
    http.get('/user/list').then(res => {
        console.log(res);
    })

  • API调用【强烈推荐】
    在调用流程中增加 api 层，用来管理所有的api连接和参数设置信息，具体如下：

    • 创建 api 目录，位置如：/utils/api

    提示
    1、该目录一般存储后端 api 调用初始化文件。
    2、目录名称和创建位置可以自定义。

    • 创建 api 模块，如 /utils/api/user.uts，并初始化

      /**
      * 用户模块接口管理
      */
      import { http } from '../http';
      // 这里的类型需要从请求库里面导入使用，因为目前 uts 不支持插件导出的类型在外部模块之间共享。。。
      import { RequestConfig } from '@/uni_modules/kux-request';
      
      interface IUser {
          info(id: number, options: RequestConfig): Promise<any>;
      };
      
      class User implements IUser {
          info(id: number, options: RequestConfig): Promise<any> {
              return http.get(`/user/detail/${id}`, options);
          }
      };
      
      export const useUser = (): User => {
          return new User();
      }

    • 页面直接引入使用

      import { useUser } from '@/utils/api/user';
      import { RequestConfig } from '@/uni_modules/kux-request';
      
      useUser().info(1, {} as RequestConfig).then((res) => {
          console.log(res);
      }).catch((err) => {
          console.log(err);
      })

      提示
      由于 uts 全局挂载请求库使用会有类型解析问题，所以目前不支持全局挂载使用

全局挂载【由于uts编译器泛型解析问题，目前全局挂载不可用】

main.uts 全局挂载

下载该 uni_modules 插件到自己的项目中后，可以直接在项目根目录的 main.uts 进行全局引入挂载，方便后面直接调用，示例代码如下：

import App from './App.uvue';

import { createSSRApp } from 'vue';
// 引入 kux-request 请求库
import {useRequest, UseOptions} from '@/uni_modules/kux-request';

export function createApp() {
    const app = createSSRApp(App);
    // 通过 app.use 全局挂载请求库，这里建议使用有意义的且不容易和全局内置变量冲突的名字
    // 请求配置可以放到单独的模块中方便管理   
    app.config.globalProperties.kuxRequest = useRequest({
        baseURL: '', // 这里填写自己的请求域名，建议提供 `env` 全局管理
    } as UseOptions);
    return {
        app
    }
}

为了方便统一话术，上面的 kuxRequest 在下文中统称为 request

页面发起请求

this.kuxRequest.get('/user/list')
    .then((res) => {
        // 获取请求结果
        console.log(res);
    })
    .catch((err) => {
        // 获取异常
        console.log(err);
    })

进阶

请求/响应拦截

请求库提供了 useInterceptor拦截管理器来完成请求/响应拦截场景，其中请求拦截支持 同步拦截 和 异步拦截，你可以用拦截管理器来实现如下场景

• 设置请求 header
• 获取请求 token
• 刷新请求 token
• 修改请求参数

示例代码

import { useInterceptor, RequestConfig } from '@/uni_modules/kux-request';

const interceptor = useInterceptor();
interceptor
        .useRequestSync(async (options): Promise<RequestConfig> => {
            console.log('同步请求拦截', options);
            options.data = {
                a: 2
            };
            return options;
        })
        .useRequest((options): RequestConfig => {
            console.log('请求拦截', options);
            options.data = {
                a: 1
            }
            return options;
        })
        .useResponse((res): any => {
            if (typeof res === 'object') {
                console.log('响应拦截', (res as UTSJSONObject).getAny('route'));
                res.set('route', '/a/b/c');
            }

            if (typeof res === 'string') {
                res = '拦截成功了';
            }

            return res;
        })

请求过滤

请求库提供了 useFilter 过滤器来完成请求过滤场景，你也可以设置请求配置 filterRequest 参数为 true 实现请求过滤。

注意
过滤器和请求配置同时开启过滤时只有过滤器会生效

过滤器使用示例

import { useFilter, FilterOptinos } from '@/uni_modules/kux-request';

const filter = useFilter({
    debug: true
} as FilterOptions);

filter.filterRequest('/user/list', options, async (): Promise<any> => {
    return request.get('/user/list?name=mary', options);
}).then((res) => {
    console.log('请求结果', res);
});

请求配置开启过滤使用示例

request
    .get('/user/list/?ids=2', {
        filterRequest: true, // 是否开启过滤
        debug: true
    } as RequestConfig)
    .then((res) => {
        console.log(res);
    })

请求重试

请求库提供了 useRetry 请求重试管理器来完成请求重试场景。请求重试实例创建时需要提供三个初始化参数：

• maxRetryCount : number: 最大重试次数。指定在请求失败时最多尝试多少次重试。如果请求一直失败，最多只会尝试 maxRetryCount 次重试。 ，默认为 3
• initialDelay: number：初始重试等待时间。指定在第一次请求失败后，等待多长时间后再尝试重试。单位是毫秒。 默认为 1000
• maxDelay: number：最大重试等待时间。指定在重试过程中，等待时间最多不超过多少毫秒。这个参数可以防止等待时间过长。 默认为 10000

使用示例

import { useRetry } from '@/uni_modules/kux-request';

const retry = useRetry(3, 1000, 10000);
retry.sendRequest('https://test1.api.fdproxy.cn/user/list')
                .then((res) => {
                    console.log(res);
                })
                .catch((err) => {
                    console.log(err);
                })

批量请求

请求库提供了 useBatchRequest 批量请求管理器来完成批量请求场景。批量请求管理器提供了 addRequest 逐个添加和 addBatchRequest 批量添加两种方式去添加请求队列。

使用示例

import { useBatchRequest } from '@/uni_modules/kux-request';

async function fetchData(url: string): Promise<any> {
  // 模拟异步请求
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(`Data from ${url}`);
    }, Math.random() * 1000);
  });
}

const batchManager = useBatchRequest();

// 逐个添加请求演示
// batchManager.addRequest(fetchData('https://api.example.com/data1'));
// batchManager.addRequest(fetchData('https://api.example.com/data2'));
// batchManager.addRequest(fetchData('https://api.example.com/data3'));

// 批量添加请求演示
const requests = [
    fetchData('https://api.example.com/data1'),
    fetchData('https://api.example.com/data2'),
    fetchData('https://api.example.com/data3')
];

batchManager.addBatchRequest(requests);

// 执行批量请求
async function main () {
    const results = await batchManager.executeBatch();

    // 处理结果
    console.log(results);
}

main();

中断请求

请求库支持中断当前请求。其实还是 uni.request 的 RequestTask 请求任务实例的 abort

request().abort();

请求配置

请求库的请求配置分为创建请求实例时传的 默认配置 和 发起请求时传的 请求配置。请求配置 会覆盖 默认配置 的同名参数值。

默认配置

baseURL

• 描述：接口服务器域名，建议通过 .env 统一管理。
• 类型：string
• 默认值：''
• 是否必填：是

query

• 描述：请求的query参数，即最后拼接在地址栏后面的参数，如：/user/info?id=1
• 类型：UTSJSONObject | null
• 默认值：null
• 是否必填：否

data

• 描述：请求的data参数
• 类型：RequestDataOptions
• 默认值：null
• 是否必填：否

header

• 描述：设置请求的 header，header 中不能设置 Referer
• 类型：UTSJSONObject | null
• 默认值：null
• 是否必填：否

timeout

• 描述：超时时间，单位 ms
• 类型：number | null
• 默认值：60000
• 是否必填：否

dataType

• 描述：如果设为 json，会对返回的数据进行一次 JSON.parse，非 json 不会进行 JSON.parse
• 类型：string | null
• 默认值：json
• 是否必填：否

responseType

• 描述：设置响应的数据类型。
• 类型：string | null
• 默认值：null
• 是否必填：否

sslVerify

• 描述：验证 ssl 证书
• 类型：boolean | null
• 默认值：false
• 是否必填：否

withCredentials

• 描述：跨域请求时是否携带凭证（cookies）
• 类型：boolean | null
• 默认值：false
• 是否必填：否

firstIpv4

• 描述：DNS解析时优先使用ipv4
• 类型：boolean | null
• 默认值：false
• 是否必填：否

filterRequest

• 描述：过滤重复请求
• 类型：boolean | null
• 默认值：false
• 是否必填：否

debug

• 描述：开启 debug 模式
• 类型：boolean | null
• 默认值：false
• 是否必填：否

xhrCode

• 描述：响应自定义成功状态码，只有响应的自定义成功状态码匹配时才会返回响应结果
• 类型：any | null
• 默认值：null
• 是否必填：否

xhrCodeName

• 描述：响应自定义状态码字段名，成功响应的自定义状态码名称，比如 code, statusCode等
• 类型：string | null
• 默认值：null
• 是否必填：否

xhrMessageName

• 描述：响应自定义描述内容字段名，成功响应的自定义描述内容字段名，比如 msg, message 等
  
  • 在定义了 xhrCode 和 xhrCodeName 时，该参数有效，当自定义成功状态码不匹配时作为catch返回的描述语
• 类型：string | null
• 默认值：null
• 是否必填：否

openCache

• 描述：开启请求缓存
• 类型：boolean | null
• 默认值：false
• 是否必填：否

maxCacheSize

• 描述：最大缓存数量
  • 开启请求缓存时有效
• 类型：number | null
• 默认值：10
• 是否必填：否

发起请求配置

url

• 描述：接口地址
• 类型：string
• 默认值：''
• 是否必填：是

query

• 描述：请求的query参数，即最后拼接在地址栏后面的参数，如：/user/info?id=1
• 类型：UTSJSONObject | null
• 默认值：null
• 是否必填：否

data

• 描述：请求的data参数
• 类型：RequestDataOptions
• 默认值：null
• 是否必填：否

header

• 描述：设置请求的 header，header 中不能设置 Referer
• 类型：UTSJSONObject | null
• 默认值：null
• 是否必填：否

timeout

• 描述：超时时间，单位 ms
• 类型：number | null
• 默认值：60000
• 是否必填：否

dataType

• 描述：如果设为 json，会对返回的数据进行一次 JSON.parse，非 json 不会进行 JSON.parse
• 类型：string | null
• 默认值：json
• 是否必填：否

responseType

• 描述：设置响应的数据类型。
• 类型：string | null
• 默认值：null
• 是否必填：否

sslVerify

• 描述：验证 ssl 证书
• 类型：boolean | null
• 默认值：false
• 是否必填：否

withCredentials

• 描述：跨域请求时是否携带凭证（cookies）
• 类型：boolean | null
• 默认值：false
• 是否必填：否

firstIpv4

• 描述：DNS解析时优先使用ipv4
• 类型：boolean | null
• 默认值：false
• 是否必填：否

filterRequest

• 描述：过滤重复请求
• 类型：boolean | null
• 默认值：false
• 是否必填：否

debug

• 描述：开启 debug 模式
• 类型：boolean | null
• 默认值：false
• 是否必填：否

xhrCode

• 描述：响应自定义成功状态码，只有响应的自定义成功状态码匹配时才会返回响应结果
• 类型：any | null
• 默认值：null
• 是否必填：否

xhrCodeName

• 描述：响应自定义状态码字段名，成功响应的自定义状态码名称，比如 code, statusCode等
• 类型：string | null
• 默认值：null
• 是否必填：否

xhrMessageName

• 描述：响应自定义描述内容字段名，成功响应的自定义描述内容字段名，比如 msg, message 等
  
  • 在定义了 xhrCode 和 xhrCodeName 时，该参数有效，当自定义成功状态码不匹配时作为catch返回的描述语
• 类型：string | null
• 默认值：null
• 是否必填：否

openCache

• 描述：开启请求缓存
• 类型：boolean | null
• 默认值：false
• 是否必填：否

maxCacheSize

• 描述：最大缓存数量
  • 开启请求缓存时有效
• 类型：number | null
• 默认值：10
• 是否必填：否

xhrResponse

• 描述：是否直接返回原始响应内容
  • v1.0.8 及以上版本支持
• 类型：boolean
• 默认值：false
• 是否必填：否

• 示例代码

  request.post('/user/create', {
      data: {
          name: 'Tom',
          age: 24
      },
      xhrResponse: true
  } as RequestConfig)
  .then((res) => {
      console.log(res);
  })
  .catch((err) => {
      console.log(err);
  })

错误码规范

错误码规范是完全遵循 uni错误规范 设计。具体错误码格式定义如下：

90 + 模块代码 + 错误码，其中目前 模块代码 定义如下：

完整错误码定义如下：

API

get

get请求，支持 query传参 和 地址栏传参，见下方使用示例。

地址栏传参

参数直接拼接在接口地址后面即可

request.get('/user/info?id=1')
    .then((res) => {
        // 此处可自定义业务逻辑
    })
    .catch((res) => {
        // 此处仅为演示
        console.error('请求服务异常');    
    });

query传参

可以在请求配置里面传 query 参数，参数类型为 UTSJSONObject

提示
请求库会自动转为 query string 形式拼接在 地址栏传参后面

request.get('/user/info', {
    query: {
        id: 1
    }
} as RequestConfig)
    .then((res) => {
        // 此处可自定义业务逻辑
    })
    .catch((err) => {
        // 此处仅为演示
        console.error('请求服务异常');
    });

post

post请求方法

request.post('/user/save', {
    data: {
        user_id: 1
    }
} as RequestConfig)
    .then((res) => {
        // 此处可自定义业务逻辑
    })
    .catch((err) => {
        // 此处仅为演示
        console.error('请求服务异常');
    });

put

put请求方法

request.put('/user/edit', {
    data: {
        user_id: 1
    }
} as RequestConfig)
    .then((res) => {
        // 此处可自定义业务逻辑
    })
    .catch((err) => {
        // 此处仅为演示
        console.error('请求服务异常');
    });

delete

delete请求方法，传参方式同 get 请求。

request.put('/user/edit', {
    query: {
        user_id: 1
    }
} as RequestConfig)
    .then((res) => {
        // 此处可自定义业务逻辑
    })
    .catch((err) => {
        // 此处仅为演示
        console.error('请求服务异常');
    });

request

request请求方法，可以通过 method 请求参数指定请求方式。

request.request('/user/info', {
    method: 'GET'
} as RequestConfig)
    .then((res) => {
        // 此处可自定义业务逻辑
    })
    .catch((err) => {
        // 此处仅为演示
        console.error('请求服务异常');
    });

getKey

用来获取当前请求的 key 标识，通过 url 参数和 options 请求配置拼接而成的字符串。定义如下：

${url}-${JSON.stringify(options)}

cache

获取指定key的请求缓存结果。key默认为 url-options

request
    .cache()
    .get('/user/list?ids=2')
    .then((res) => {
        console.log('请求结果2', res);
    })
    .catch((err) => {
        console.log('请求失败2', err);
    })

注意
需要在 openCache 为 true 时才生效

overrideConfig

复写当前实例的全局配置，比如data，query，header等参数

request
    .overrideConfig({
        query: {}
    } as RequestConfig)
    .post('/user/create', {
        data: {
            name: 'Tom',
            age: 21
        }
    } as RequestConfig)

提示

目前仅 baseURL、query、data 和 header 设置生效。

clearCache

清除指定key的请求缓存。如果key为空则清空当前请求实例所有的请求缓存。

abort

中断当前请求。

onFail

捕获全局请求失败的错误信息。

request.onFail((fail: RequestFail) => {
    console.log('请求失败拦截', fail);
});

提示

v1.0.10 及以上版本支持

组合式API

useRequest

用来创建管理 request 实例。

属性

requestTask

• 描述：获取当前请求任务。
• 类型：RequestTask | null。

beforeSendOptions

• 描述：获取发起请求前的请求配置。
• 类型：RequestConfig | null

方法

同 API。

useInterceptor

用来创建和管理 拦截器 实例。

属性

无

方法

useRequest

useRequest(interceptor: RequestInterceptor): InterceptorManager

请求异步拦截。参考 请求/响应拦截。

useRequestSync

useRequestSync(interceptor: RequestInterceptorSync): InterceptorManager

请求同步拦截。参考 请求/响应拦截。

useResponse

useResponse(interceptor: ResponseInterceptor): InterceptorManager

响应拦截。参考 请求/响应拦截。

提示
暂不支持同步响应拦截。

useResponseXhr

useResponseXhr (interceptor: KuxRequest.ResponseXhrInterceptor): InterceptorManager

原始响应拦截。回调函数返回的参数为 uni.request 成功回调的 res 值。

提示

• v1.0.11 及以上版本支持
• 使用该拦截器后会和 useResponse 冲突，所以两个拦截器一次只能使用一个，不然会使应用闪退，该问题在 v1.0.11 及以后版本修复。

const interceptor = useInterceptor();
interceptor
    .useResponseXhr((res: RequestSuccess<any>): any => {
        console.log('原始响应拦截', res);
        if (typeof res.data === 'object') {
            const data = res.data as UTSJSONObject;
            console.log(data.getAny('data'));
        }
        return res;
    })

useFilter

用来创建和管理 过滤器 实例。

属性

无

方法

filterRequest

filterRequest(url: string, options: RequestConfig = {} as RequestConfig, request: () => Promise<any>): Promise<any>

发起请求。

useURL

方便操作地址栏参数处理。同 js 的 URL 类。

属性

protocol

• 描述：请求协议，即 http 或 https
• 类型：string

host

• 描述：请求域名
• 类型：string

pathname

• 描述：接口地址，如：/user/info
• 类型：string

search

• 描述：地址栏参数字符串，如：?id=1&name=bob
• 类型：string

searchParams

• 描述：地址栏参数集合，如：{id: 1, name: bob}
  • 可以通过参数内置的get方法获取具体参数值，如：searchParams.get('name')
• 类型：URLSearchParams

方法

href

href(): string

获取完整的请求地址，如：https://test.api.fdproxy.cn/user/info?id=1&name=bob

使用示例

try {
    const url = useURL('https://test.api.fdproxy.cn/user/info?id=1&name=bob');
    console.log(url.protocol);
    console.log(url.host);
    console.log(url.pathname);
    console.log(url.search);
    console.log(url.searchParams.get('id'));
    console.log(url.searchParams.get('name'));
} catch (e) {
    console.log(e);
}

useUtils

创建和管理工具库实例。

属性

无

方法

objToQueryString

objToQueryString (queryObj: UTSJSONObject): string

对象转查询字符串。

const utils = useUtils();
console.log(utils.objToQueryString({
    a: 1,
    b: 2
})); // 输出 a=1&b=2

sleep

sleep (ms: number): Promise<any>

程序暂停几秒。

useRetry

创建和管理 请求重试 实例。

属性

无

方法

sendRequest

sendRequest (url: string, options: RequestConfig = {} as RequestConfig): Promise<any>

发起请求方法。

注意
请求配置是不会继承 request 请求实例的请求配置，发起请求时需要完整的请求地址和请求配置信息。

useBatchRequest

创建和管理 批量请求 实例。

属性

无

方法

addRequest

addRequest (request: Promise<any>): Promise<any>

逐个添加请求队列。

addBatchRequest

addBatchRequest (requests: Promise<any>[]): Promise<any>[]

批量添加请求队列。

executeBatch

async executeBatch (): Promise<any[]>

执行批量请求。

自定义type

由于 uts 强类型语言原因，所以请求库的自定义类型提供给开发者根据实际情况灵活引用。

UseOptions

export type UseOptions = {
    /**
     * 开发者服务器域名
     */
    baseURL: string;
    /**
     * 请求的query参数，即最后拼接在地址栏后面的参数，如：`/user/info?id=1`
     * @defaultValue null
     */
    query?: UTSJSONObject | null,
    /**
     * 请求的参数 UTSJSONObject|string类型
     * @type {RequestDataOptions}
     * @defaultValue null
     */
    data?: any | null,
    /**
     * 设置请求的 header，header 中不能设置 Referer
     * @defaultValue null
     */
    header?: UTSJSONObject | null,
    /**
     * 超时时间，单位 ms
     * @defaultValue 60000
     */
    timeout?: number | null;
    /**
     * 如果设为 json，会对返回的数据进行一次 JSON.parse，非 json 不会进行 JSON.parse
     * @defaultValue "json"
     * @deprecated 不支持
     * @autodoc false
     */
    dataType?: string | null;
    /**
     * 设置响应的数据类型。
     * 
     * @deprecated 不支持
     * @autodoc false
     */
    responseType?: string | null;
    /**
     * 验证 ssl 证书
     * 
     * @deprecated 不支持
     * @autodoc false
     */
    sslVerify?: boolean | null,
    /**
     * 跨域请求时是否携带凭证（cookies）
     * 
     * @uniPlatform {
     *    "app": {
     *        "android": {
     *            "osVer": "4.4",
     *               "uniVer": "√",
     *           "unixVer": "x"
     *        },
     *        "ios": {
     *            "osVer": "9.0",
     *               "uniVer": "√",
     *           "unixVer": "x"
     *        }
     *    }
     * }
     * 
     */
    withCredentials?: boolean | null,
    /**
     * DNS解析时优先使用ipv4
     * @defaultValue false
     */
    firstIpv4?: boolean | null,
    /**
     * 过滤重复请求
     * @defaultValue false
     */
    filterRequest?: boolean | null,
    /**
     * 开启 debug 模式
     * @defaultValue false
     */
    debug?: boolean | null,
    /**
     * 响应自定义成功状态码
     * @description 只有响应的自定义成功状态码匹配时才会返回响应结果
     */
    xhrCode?: any | null,
    /**
     * 响应自定义状态码字段名
     * @description 成功响应的自定义状态码名称，比如 code, statusCode等
     */
    xhrCodeName?: string | null,
    /**
     * 响应自定义描述内容字段名
     * @description 成功响应的自定义描述内容字段名，比如 msg, message 等
     * + 在定义了 `xhrCode` 和 `xhrCodeName` 时，该参数有效，当自定义成功状态码不匹配时作为catch返回的描述语
     */
    xhrMessageName?: string | null,
    /**
     * 开启请求缓存
     */
    openCache?: boolean | null,
    /**
     * 最大缓存数量
     * @description 开启请求缓存时有效
     */
    maxCacheSize?: number | null
    /**
     * 是否直接返回原始响应内容
     * + `v1.0.8` 及以上版本支持
     */
    xhrResponse?: boolean
};

RequestConfig

export type RequestConfig = {
    /**
     * 开发者服务器域名
     */
    baseURL?: string,
    /**
     * 开发者服务器接口地址
     */
    url?: string,
    /**
     * 请求的query参数，即最后拼接在地址栏后面的参数，如：`/user/info?id=1`
     * @defaultValue null
     */
    query?: UTSJSONObject | null,
    /**
     * 请求的参数 UTSJSONObject|string类型
     * @type {RequestDataOptions}
     * @defaultValue null
     */
    data?: any | null,
    /**
     * 设置请求的 header，header 中不能设置 Referer
     * @defaultValue null
     */
    header?: UTSJSONObject | null,
    /**
     * 请求方法
     * 如果设置的值不在取值范围内，会以GET方法进行请求。
     * @type {RequestMethod}
     * @defaultValue "GET"
     */
    method?: RequestMethod | null;
    /**
     * 超时时间，单位 ms
     * @defaultValue 60000
     */
    timeout?: number | null;
    /**
     * 如果设为 json，会对返回的数据进行一次 JSON.parse，非 json 不会进行 JSON.parse
     * @defaultValue "json"
     * @deprecated 不支持
     * @autodoc false
     */
    dataType?: string | null;
    /**
     * 设置响应的数据类型。
     * 
     * @deprecated 不支持
     * @autodoc false
     */
    responseType?: string | null;
    /**
     * 验证 ssl 证书
     * 
     * @deprecated 不支持
     * @autodoc false
     */
    sslVerify?: boolean | null,
    /**
     * 跨域请求时是否携带凭证（cookies）
     * 
     * @uniPlatform {
     *    "app": {
     *        "android": {
     *            "osVer": "4.4",
     *               "uniVer": "√",
     *           "unixVer": "x"
     *        },
     *        "ios": {
     *            "osVer": "9.0",
     *               "uniVer": "√",
     *           "unixVer": "x"
     *        }
     *    }
     * }
     * 
     */
    withCredentials?: boolean | null,
    /**
     * DNS解析时优先使用ipv4
     * @defaultValue false
     */
    firstIpv4?: boolean | null,
    /**
     * 过滤重复请求
     * @defaultValue false
     */
    filterRequest?: boolean | null,
    /**
     * 开启 debug 模式
     * @defaultValue false
     */
    debug?: boolean | null,
    /**
     * 接口自定义成功状态码
     * @description 只有响应的自定义成功状态码匹配时才会返回响应结果
     */
    xhrCode?: any | null,
    /**
     * 接口自定义状态码字段名
     * @description 成功响应的自定义状态码名称，比如 code, statusCode等
     */
    xhrCodeName?: string | null,
    /**
     * 响应自定义描述内容字段名
     * @description 成功响应的自定义描述内容字段名，比如 msg, message 等
     * + 在定义了 `xhrCode` 和 `xhrCodeName` 时，该参数有效，当自定义成功状态码不匹配时作为catch返回的描述语
     */
    xhrMessageName?: string | null,
    /**
     * 开启请求缓存
     */
    openCache?: boolean | null,
    /**
     * 最大缓存数量
     * @description 开启请求缓存时有效
     * @defaultValue 10
     */
    maxCacheSize?: number | null
    /**
     * 是否直接返回原始响应内容
     * + `v1.0.8` 及以上版本支持
     */
    xhrResponse?: boolean
};

RequestInterceptor

export type RequestInterceptor = (options: RequestConfig) => RequestConfig;

RequestInterceptorSync

export type RequestInterceptorSync = (options: RequestConfig) => Promise<RequestConfig>;

ResponseInterceptor

export type ResponseInterceptor = (response: any) => any;

ResponseInterceptorSync

export type ResponseInterceptorSync = (response: any) => Promise<any>;

ResponseXhrInterceptor

export type ResponseXhrInterceptor = (response: RequestSuccess<any>) => any;

提示

• v1.0.11 及以上版本支持
• 使用该拦截器后会和 useResponse 冲突，所以两个拦截器一次只能使用一个

RequestFailCallback

export type RequestFailCallback = (fail: RequestFail) => void;

提示

v1.0.10 及以上版本支持

Interceptors

export type Interceptors = {
    request: RequestInterceptor[],
    response: ResponseInterceptor[],
    requestSync?: RequestInterceptorSync | null,
    responseSync?: ResponseInterceptorSync | null
}

FilterOptions

export type FilterOptions = {
    debug?: boolean;
};

PendingRequests

export type PendingRequests = Map<string, Promise<any>>;

UseRetryOptions

/**
 * useRetry 初始化配置
 */
export type UseRetryOptions = {
    /**
     * 最大重试次数
     */
    maxRetryCount?: number | null;
    /**
     * 初始重试等待时间
     */
    initialDelay?: number | null;
    /**
     * 最大重试等待时间
     */
    maxDelay?: number | null;
};

KuxErrorCode

/**
 * 错误码
 * 根据uni错误码规范要求，建议错误码以90开头，以下是错误码示例：
 * - 9010001 错误信息1
 * - 9010002 错误信息2
 */
export type KuxErrorCode = 901404 | 900408 | 900500;

KuxRequestFail

export interface KuxRequestFail extends IUniError {
    errCode: KuxErrorCode
}

函数和类类型签名

/**
 * Request实例
 */
export declare class Request {
    constructor (config: UseOptions);

    public getKey (url: string, options: RequestConfig): string;

    /**
     * 清除指定key的请求缓存
     * @description 请求指定key的请求缓存，如果key为空则清空当前请求实例所有的请求缓存
     * @returns {Request}
     */
    public clearCache (key: string): Request;

    /**
     * 获取指定key的请求缓存结果
     * @description 获取指定key的请求缓存结果
     * + key默认为 `url`-`options`
     * @returns {Request}
     */
    public cache (key: string): Request;

    /**
     * 复写全局配置
     * @description 复写当前实例的全局配置，比如data，query，header参数
     * @param {RequestConfig} config 配置项
     * @returns {Request}
     */
    public overrideConfig (config: RequestConfig): Request;

    /**
     * request请求
     * @param {string} url 请求地址
     * @param {RequestConfig} options 请求配置，会覆盖全局配置
     * @returns {Promise<any>}
     */
    public request (url: string, options: RequestConfig): Promise<any>;

    /**
     * get请求
     * @param {string} url 请求地址
     * @param {RequestConfig} options 请求配置，会覆盖全局配置
     * @returns {Promise<any>}
     */
    public get (url: string, options: RequestConfig): Promise<any>;

    /**
     * post请求
     * @param {string} url 请求地址
     * @param {RequestConfig} options 请求配置，会覆盖全局配置
     * @returns {Promise<any>}
     */
    public post (url: string, options: RequestConfig): Promise<any>;

    /**
     * put请求
     * @param {string} url 请求地址
     * @param {RequestConfig} options 请求配置，会覆盖全局配置
     * @returns {Promise<any>}
     */
    public put (url: string, options: RequestConfig): Promise<any>;

    /**
     * delete请求
     * @param {string} url 请求地址
     * @param {RequestConfig} options 请求配置，会覆盖全局配置
     * @returns {Promise<any>}
     */
    public delete (url: string, options: RequestConfig): Promise<any>;

    /**
     * 中断当前请求
     */
    public abort (): void;
}

/**
 * 创建请求实例
 * @param {UseOptions} options 实例参数
 * @returns {Request} 返回请求实例对象
 */
export declare function useRequest (options: UseOptions): Request;

/**
 * 拦截器实例
 */
export declare class InterceptorManager {
    constructor ();

    /**
     * 请求拦截
     * @param {RequestInterceptor} 拦截器回调
     */
    public useRequest(interceptor: RequestInterceptor): InterceptorManager;

    /**
     * 同步请求拦截
     * @param {RequestInterceptorSync} 拦截器回调
     */
    public useRequestSync(interceptor: RequestInterceptorSync): InterceptorManager;

    /**
     * 响应拦截
     * @param {ResponseInterceptor} 拦截器回调
     */
    public useResponse(interceptor: ResponseInterceptor): InterceptorManager;
}

/**
 * 创建拦截器实例
 * @returns {InterceptorManager} 返回拦截器实例对象
 */
export declare function useInterceptor ():  InterceptorManager;

/**
 * 过滤器实例
 */
export declare class RequestFilters {
    constructor (options?: FilterOptions);

    /**
     * 请求过滤器
     */
    public filterRequest(url: string, options: RequestConfig, request: () => Promise<any>): Promise<any>;
}

/**
 * 创建过滤器实例
 * @returns {RequestFilters} 返回过滤器实例对象
 */
export declare function useFilter(options?: FilterOptions): RequestFilters;

/**
 * URL搜索参数实例
 */
export declare class URLSearchParams {
    constructor (search: string);

    public get(key: string): string | null;
}

/**
 * URL实例
 */
export declare class URL {
    /**
     * 请求协议，即 http 或 https
     */
    public protocol: string;
    /**
     * 请求域名
     */
    public host: string;
    /**
     * 接口地址，如：/user/info
     */
    public pathname: string;
    /**
     * 地址栏参数字符串，如：?id=1&name=bob
     */
    public search: string;
    /**
     * 地址栏参数集合，如：{id: 1, name: bob}
     */
    public searchParams: URLSearchParams;

    constructor (url: string);

    /**
     * 获取完整的请求地址，如：https://test.api.fdproxy.cn/user/info?id=1&name=bob
     */
    public get href (): string;
}

/**
 * 创建URL实例
 * @returns {URL} 返回URL实例对象
 */
export declare function useURL (url: string): URL;

/**
 * 工具类实例
 */
export declare class Utils {
    /**
     * 对象转查询字符串
     * @param {UTSJSONObject} queryObj 对象
     * @returns {string}
     */
    public objToQueryString(queryObj: UTSJSONObject): string;

    /**
     * 构建uni标准错误对象
     * @param {string} errSubject 错误对象模块名称，如：kux-request
     * @param {number} errCode 错误码
     * @param {string} errMsg 错误内容
     * @param {string} cause 源错误内容
     * @returns {UniError} uni 统一错误对象
     */
    public buildUniError(errSubject: string, errCode: number, errMsg: string, cause?: string): UniError;

    /**
     * 程序暂停几秒。
     * @param {number} ms 暂停的毫秒数
     */
    public sleep(ms: number): Promise<any>;

    /**
     * 两个对象深度合并
     * @param {any} 目标对象
     * @param {any} 源对象
     */
    public deepMerge(target: any, source: any): any;
}

/**
 * 创建工具实例
 * @returns {Utils} 返回工具类实例对象
 */
export declare function  useUtils () : Utils;

/**
 * 重试实例
 */
export declare class RetryManager extends Request {
    constructor (maxRetryCount: number, initialDelay: number, maxDelay: number);

    /**
     * 发送请求
     * @param {string} url 完整的请求URL
     * @param {RequestConfig} options 请求配置
     */
    public sendRequest(url: string, options?: RequestConfig): Promise<any>;
}

/**
 * 创建请求重试实例
 * @param {number} maxRetryCount 最大重试次数。指定在请求失败时最多尝试多少次重试。如果请求一直失败，最多只会尝试 `maxRetryCount` 次重试。
 * @param {number} initialDelay 初始重试等待时间。指定在第一次请求失败后，等待多长时间后再尝试重试。单位是毫秒。
 * @param {number} maxDelay 最大重试等待时间。指定在重试过程中，等待时间最多不超过多少毫秒。这个参数可以防止等待时间过长。
 * @returns {RetryManager} 返回请求重试实例对象
 */
export declare function useRetry (maxRetryCount: number, initialDelay: number, maxDelay: number) : RetryManager;

/**
 * 批量请求实例
 */
export declare class BatchRequestManager {
    /**
     * 逐个添加请求队列。
     * @param {Promise<any>} request 请求队列
     * @returns {Promise<any>} 请求队列Promise对象
     */
    public addRequest(request: Promise<any>): Promise<any>;

    /**
     * 批量添加请求队列。
     * @param {Promise<any>[]} requests 请求队列
     * @returns {Promise<any>[]} 请求队列Promise对象集合
     */
    public addBatchRequest(requests: Promise<any>[]): Promise<any>[];

    /**
     * 执行批量请求。
     * @returns {Promise<any>[]} 请求队列Promise对象集合
     */
    public executeBatch(): Promise<any[]>;
}

/**
 * 创建和管理 批量请求 实例。
 * @returns {BatchRequestManager} 返回批量请求实例对象
 */
export declare function useBatchRequest () : BatchRequestManager;

说明

Hbuilder X 4.0 及以上版本支持。

结语

kux 不生产代码，只做代码的搬运工，致力于提供uts 的 js 生态轮子实现，欢迎各位大佬在插件市场搜索使用 kux 生态插件：https://ext.dcloud.net.cn/search?q=kux

QQ群：870628986 点击加入

友情推荐

• TMUI4.0：包含了核心的uts插件基类.和uvue组件库
• GVIM即时通讯模版：GVIM即时通讯模版，基于uni-app x开发的一款即时通讯模版
• t-uvue-ui：T-UVUE-UI是基于UNI-APP X开发的前端UI框架
• UxFrame 低代码高性能UI框架：【F2图表、双滑块slider、炫酷效果tabbar、拖拽排序、日历拖拽选择、签名...】UniAppX 高质量UI库
• wx-ui 基于uni-app x开发的高性能混合UI库：基于uni-app x开发的高性能混合UI库，集成 uts api 和 uts component，提供了一套完整、高效且易于使用的UI组件和API，让您以更少的时间成本，轻松完成高性能应用开发。
• firstui-uvue：FirstUI（unix）组件库，一款适配 uni-app x 的轻量、简洁、高效、全面的移动端组件库。
• easyXUI 不仅仅是UI 更是为UniApp X设计的电商模板库：easyX 不仅仅是UI库，更是一个轻量、可定制的UniAPP X电商业务模板库，可作为官方组件库的补充,始终坚持简单好用、易上手
• OneUI：致力于提供简洁、现代的 UI 组件，帮助开发者快速构建美观、功能丰富的移动应用程序。