diff --git a/packages/horizon-request/README.md b/packages/horizon-request/README.md index 2e0772a6..22060fc1 100644 --- a/packages/horizon-request/README.md +++ b/packages/horizon-request/README.md @@ -1,28 +1,34 @@ -# Horizon-Request +# Inula-request -### 1 horizon-request请求方法 +欢迎使用`Inula-request`请求组件,接下来本文档将对`Inula-request` API使用进行一个详细介绍,帮助您更便捷的发送网络请求! -方便起见,该文档将使用`hr`别名介绍`horizon-request`请求方法,即使用如下方式导入请求组件: +## inula-request请求方法引入 + +方便起见,该文档将使用`ir`别名介绍`Inula-request`请求方法,即使用如下方式导入请求组件: ```typescript -import hr from 'horizon-request'; +import ir from 'inula-request'; ``` -#### 1.1 hr(config) +## inula-request 全局 API -该请求方法为通用请求方法,可以通过配置config参数完成多种形式的网络请求,关于config具体参数配置将在参数配置章节详细介绍。 +### ir(config) -##### 1.1.1 接口定义 +**功能介绍** + +该请求方法为通用请求方法,可以通过配置config参数完成多种形式的网络请求,关于config具体参数配置将在[参数配置章节](#请求配置全量参数)详细介绍。 + +**接口定义** ```typescript -hr(config: HrRequestConfig): Promise>; +ir(config: IrRequestConfig): Promise>; ``` -其中请求配置参数类型`HrRequestConfig`和请求响应类型`HrResponse`定义如下: +其中请求配置参数类型`IrRequestConfig`和请求响应类型`IrResponse`定义如下: ```typescript // 请求配置 -interface HrRequestConfig { +interface IrRequestConfig { url?: string; method?: Method; @@ -30,12 +36,6 @@ interface HrRequestConfig { // 公共URL前缀 baseURL?: string; - // 请求数据转换器 - transformRequest?: HrTransformer | HrTransformer[]; - - // 响应数据转换器 - transformResponse?: HrTransformer | HrTransformer[]; - headers?: Record; params?: Record | null; @@ -75,7 +75,7 @@ interface HrRequestConfig { } // 请求响应 -type HrResponse = { +type IrResponse = { // 响应数据 data: T; @@ -89,7 +89,7 @@ type HrResponse = { headers: any; // 请求配置 - config: HrRequestConfig; + config: IrRequestConfig; // 请求对象 request?: any; @@ -99,17 +99,17 @@ type HrResponse = { }; ``` -##### 1.1.2 代码示例 +**示例** ```typescript -hr({ +ir({ url: 'https://www.example.com/data', method: 'POST', headers: { 'Content-Type': 'application/json' }, data: { - name: 'horizon-request' + name: 'inula-request' }, timeout: 5000 }) @@ -121,22 +121,24 @@ hr({ }); ``` -使用`hr(config)`方法可以灵活地定制请求的各个参数,以满足特定的需求,同时注意正确处理成功响应和错误情况。 +使用`ir(config)`方法可以灵活地定制请求的各个参数,以满足特定的需求,并注意正确处理成功响应和错误情况。 -#### 1.2 hr(url[, config]) +### ir(url[, config]) -该接口提供一种简化的请求方式,您可以将网络请求的`url`作为请求方法的第一个参数,省略其他复杂的配置,`horizon-request`请求组件将为您发送一个默认的`get`请求,在多数简单`get`请求场景中,您可以使用这种方式来简化您的代码。 +**功能介绍** -##### 1.2.1 接口定义 +该接口提供一种简化的请求方式,您可以将网络请求的`URL`作为请求方法的第一个参数,省略其他复杂的配置,`inula-request`请求组件将为您发送一个默认的`GET`请求,在多数简单`GET`请求场景中,您可以使用这种方式来简化您的代码。 + +**接口定义** ```typescript -hr(url: string[, config: HrRequestConfig]): Promise>; +ir(url: string[, config: IrRequestConfig]): Promise>; ``` -##### 1.2.2 代码示例 +**示例** ```typescript -hr('https://www.example.com/data', { +ir('https://www.example.com/data', { method: 'GET', headers: { 'Content-Type': 'application/json' @@ -150,7 +152,7 @@ hr('https://www.example.com/data', { }); // 简化写法 -hr('https://www.example.com/data') +ir('https://www.example.com/data') .then(response => { // 处理成功响应 }) @@ -159,25 +161,39 @@ hr('https://www.example.com/data') }); ``` -#### 1.3 hr.request(config) & hr.request(url[, config]) +在上面的示例中,将 `url` 作为请求的第一个参数,发送了一个 `GET` 请求,您也可以使用第二个示例这种简化形式,不显式设置请求方法会默认发送 `GET` 请求并配置正确的 `Content-Type` 请求头。 -该接口为`hr(config) & hr(url[, config])`的完整表达方式,`hr(config) & hr(url[, config])`是网络请求的语法糖,其功能完全等同,接口定义和代码使用用法参见1.1和1.2章节。 +### ir.request(config) & ir.request(url[, config]) -#### 1.4 hr.get(url[, config]) +**功能介绍** + +`ir.request(config) & ir.request(url[, config])`为`ir(config) & ir(url[, config])`的完整表达方式,其功能完全等同,接口定义和代码使用用法参见 [ir(config)](#ir(config)) 和 [ir(url[, config])](#ir(config)) 章节。 + +**接口定义** + +见 ir(config)和 ir(url[, config])章节。 + +**示例** + +见 ir(config)和 ir(url[, config])章节。 + +### ir.get(url[, config]) + +**功能介绍** 该接口将发送`GET`网络请求并返回一个`Promise`对象。 -##### 1.4.1 接口定义 +**接口定义** ```typescript -hr.get(url: string, config?: HrRequestConfig): Promise>; +ir.get(url: string, config?: IrRequestConfig): Promise>; ``` -##### 1.4.2 代码示例 +**示例** ```typescript // 使用默认配置发送GET请求 -hr.get('https://www.example.com/data') +ir.get('https://www.example.com/data') .then(response => { // 请求成功,处理响应数据 }) @@ -186,7 +202,7 @@ hr.get('https://www.example.com/data') }); // 使用自定义配置发送GET请求 -hr.get('https://www.example.com/data', { +ir.get('https://www.example.com/data', { params: { id: 123, sortBy: 'name' @@ -204,23 +220,25 @@ hr.get('https://www.example.com/data', { }); ``` -上述示例中,通过`hr.get`方法发送一个GET请求到`https://www.example.com/data`。在请求成功后,通过`response.data`访问服务器返回的数据。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 +上述示例中,通过`ir.get`方法发送一个GET请求到`https://www.example.com/data`。在请求成功后,通过`response.data`访问服务器返回的数据。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 -#### 1.5 hr.post(url[, data[, config]]) +### ir.post(url[, data[, config]]) + +**功能介绍** 该接口将发送`POST`网络请求并返回一个`Promise`对象。 -##### 1.5.1 接口定义 +**接口定义** ```typescript -hr.post(url: string, data?: any, config?: HrRequestConfig): Promise>; +ir.post(url: string, data?: any, config?: IrRequestConfig): Promise>; ``` -##### 1.5.2 代码示例 +**示例** ```typescript // 使用默认配置发送POST请求 -hr.post('https://www.example.com/data', { +ir.post('https://www.example.com/data', { name: 'Xiao Ming', age: 18 }) @@ -232,7 +250,7 @@ hr.post('https://www.example.com/data', { }); // 使用自定义配置发送POST请求 -hr.post('https://www.example.com/data', { +ir.post('https://www.example.com/data', { name: 'Xiao Ming', age: 18 }, { @@ -249,23 +267,24 @@ hr.post('https://www.example.com/data', { }); ``` -上述示例中,通过`hr.post`方法发送一个POST请求到`https://www.example.com/data`,并传递了一个包含`name`和`age`字段的数据对象。在请求成功后,通过`response.data`访问服务器返回的数据。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 +上述示例中,通过`ir.post`方法发送一个POST请求到`https://www.example.com/data`,并传递了一个包含`name`和`age`字段的数据对象。在请求成功后,通过`response.data`访问服务器返回的数据。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 -#### 1.6 hr.delete(url[, config]) +### ir.delete(url[, config]) +**功能介绍** 该接口将发送`DELETE`网络请求删除`url`上的资源,并返回一个`Promise`对象。 -##### 1.6.1 接口定义 +**接口定义** ```typescript -hr.delete(url: string, config?: HrRequestConfig): Promise>; +ir.delete(url: string, config?: IrRequestConfig): Promise>; ``` -##### 1.6.2 代码示例 +**示例** ```typescript // 使用默认配置发送DELETE请求 -hr.delete('https://www.example.com/data/123') +ir.delete('https://www.example.com/data/123') .then(response => { // 删除成功 }) @@ -274,7 +293,7 @@ hr.delete('https://www.example.com/data/123') }); // 使用自定义配置发送DELETE请求 -hr.delete('https://api.example.com/data/123', { +ir.delete('https://api.example.com/data/123', { params: { force: true }, @@ -291,23 +310,25 @@ hr.delete('https://api.example.com/data/123', { }); ``` -上述示例中,我们通过`hr.delete`方法发送一个DELETE请求删除`https://www.example.com/data/123`上的资源。在请求成功后,服务器成功删除`url`上的资源。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 +上述示例中,通过`ir.delete`方法发送一个DELETE请求删除`https://www.example.com/data/123`上的资源。在请求成功后,服务器成功删除`URL`上的资源。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 -#### 1.7 hr.head(url[, config]) +### ir.head(url[, config]) + +**功能介绍** 该接口将发送`HEAD`网络请求并返回一个`Promise`对象。HEAD请求方法与GET方法类似,但是服务器不会返回实际内容。它仅返回响应头,包括状态码、响应日期、服务器信息以及其他元数据 。 -##### 1.7.1 接口定义 +**接口定义** ```typescript -hr.head(url: string, config?: HrRequestConfig): Promise>; +ir.head(url: string, config?: IrRequestConfig): Promise>; ``` -##### 1.7.2 代码示例 +**示例** ```typescript // 使用默认配置发送HEAD请求 -hr.head('https://api.example.com/data') +ir.head('https://api.example.com/data') .then(response => { // 请求成功,处理响应头等信息 }) @@ -316,7 +337,7 @@ hr.head('https://api.example.com/data') }); // 使用自定义配置发送HEAD请求 -hr.head('https://api.example.com/data', { +ir.head('https://api.example.com/data', { headers: { 'X-Requested-With': 'XMLHttpRequest', 'Authorization': 'your-token' @@ -330,23 +351,25 @@ hr.head('https://api.example.com/data', { }); ``` -上述示例中,我们通过`hr.head`方法发送一个HEAD请求到`https://api.example.com/data`。在请求成功后,可以通过`response.headers`访问服务器返回的头信息等。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 +上述示例中,通过`ir.head`方法发送一个HEAD请求到`https://api.example.com/data`。在请求成功后,可以通过`response.headers`访问服务器返回的头信息等。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 -#### 1.8 hr.options(url[, config]) +### ir.options(url[, config]) + +**功能介绍** 该接口将发送`OPTIONS`网络请求目标资源所支持的请求方法、请求头等信息 ,并返回一个`Promise`对象。 -##### 1.8.1 接口定义 +**接口定义** ```typescript -hr.options(url: string, config?: HrRequestConfig): Promise>; +ir.options(url: string, config?: IrRequestConfig): Promise>; ``` -##### 1.8.2 代码示例 +**示例** ```typescript // 使用默认配置发送OPTIONS请求 -hr.options('https://www.example.com/data') +ir.options('https://www.example.com/data') .then(response => { // 请求成功,处理响应 }) @@ -355,7 +378,7 @@ hr.options('https://www.example.com/data') }); // 使用自定义配置发送OPTIONS请求 -hr.options('https://api.example.com/data', { +ir.options('https://api.example.com/data', { headers: { 'X-Requested-With': 'XMLHttpRequest', 'Authorization': 'your-token' @@ -369,23 +392,25 @@ hr.options('https://api.example.com/data', { }); ``` -上述示例中,通过`hr.options`方法发送一个OPTIONS请求到`https://api.example.com/data`。在请求成功后,我们获取访问服务器支持的请求方法、请求头等信息。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 +上述示例中,通过`ir.options`方法发送一个OPTIONS请求到`https://api.example.com/data`。在请求成功后,获取访问服务器支持的请求方法、请求头等信息。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 -#### 1.9 hr.put(url[, data[, config]]) +### ir.put(url[, data[, config]]) + +**功能介绍** 该接口将发送`PUT`网络请求更新或替换现有资源 ,并返回一个`Promise`对象。 -##### 1.9.1 接口定义 +**接口定义** ```typescript -hr.put(url: string, data?: any, config?: HrRequestConfig): Promise>; +ir.put(url: string, data?: any, config?: IrRequestConfig): Promise>; ``` -##### 1.9.2 代码示例 +**示例** ```typescript // 使用默认配置发送PUT请求 -hr.put('https://api.example.com/data/123', { +ir.put('https://api.example.com/data/123', { name: 'Xiao Ming', age: 18 }) @@ -397,7 +422,7 @@ hr.put('https://api.example.com/data/123', { }); // 使用自定义配置发送PUT请求 -hr.put('https://api.example.com/data/123', { +ir.put('https://api.example.com/data/123', { name: 'Xiao Ming', age: 18 }, { @@ -414,23 +439,25 @@ hr.put('https://api.example.com/data/123', { }); ``` -上述示例中,通过`hr.put`方法发送一个PUT请求到`https://api.example.com/data/123`,并传递了一个包含`name`和`age`字段的数据对象去更新服务端数据。在请求成功后,说明成功更新了服务端数据。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 +上述示例中,通过`ir.put`方法发送一个PUT请求到`https://api.example.com/data/123`,并传递了一个包含`name`和`age`字段的数据对象去更新服务端数据。在请求成功后,说明成功更新了服务端数据。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 -#### 1.10 hr.patch(url[, data[, config]]) +### ir.patch(url[, data[, config]]) -该接口将发送`PATCH`网络请求更新服务器上现有资源 ,并返回一个`Promise`对象。与 PUT 请求不同,PATCH 请求是对已存在的资源进行部分更新。它允许客户端发送仅包含要更新的资源的部分数据,而不需要发送整个资源的副本。 +**功能介绍** -##### 1.10.1 接口定义 +该接口将发送`PATCH`网络请求更新服务器上现有资源 ,并返回一个`Promise`对象。与 `PUT` 请求不同,`PATCH` 请求是对已存在的资源进行部分更新。它允许客户端发送仅包含要更新的资源的部分数据,而不需要发送整个资源的副本。 + +**接口定义** ```typescript -hr.patch(url: string, data?: any, config?: HrRequestConfig): Promise>; +ir.patch(url: string, data?: any, config?: IrRequestConfig): Promise>; ``` -##### 1.10.2 代码示例 +**示例** ```typescript // 使用默认配置发送PATCH请求 -hr.patch('https://api.example.com/data/123', { +ir.patch('https://api.example.com/data/123', { name: 'Xiao Ming', age: 18 }) @@ -442,7 +469,7 @@ hr.patch('https://api.example.com/data/123', { }); // 使用自定义配置发送PATCH请求 -hr.patch('https://api.example.com/data/123', { +ir.patch('https://api.example.com/data/123', { name: 'Xiao Ming', age: 18 }, { @@ -459,28 +486,30 @@ hr.patch('https://api.example.com/data/123', { }); ``` -上述示例中,我们通过`hr.patch`方法发送一个PATCH请求到`https://api.example.com/data/123`,并传递了一个包含`name`和`age`字段的数据对象。在请求成功后,说明服务端成功更新了所传入的字段值。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 +上述示例中,通过`ir.patch`方法发送一个PATCH请求到`https://api.example.com/data/123`,并传递了一个包含`name`和`age`字段的数据对象。在请求成功后,说明服务端成功更新了所传入的字段值。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 同时,您也可以传入响应头等进行自定义配置请求。 -#### 1.11 hr.all(iterable) +### ir.all(iterable) -该接口是`horizon-request`请求组件中的一个静态方法,用于同时发送多个并发请求。它接受一个可迭代对象`iterable`作为参数,该可迭代对象包含多个`hr`请求实例,方法返回一个Promise对象 。 +**功能介绍** -##### 1.11.1 接口定义 +该接口是`inula-request`请求组件中的一个静态方法,用于同时发送多个并发请求。它接收一个可迭代对象`iterable`作为参数,该可迭代对象包含多个`ir`请求实例,方法返回一个Promise对象 。 + +**接口定义** ```typescript -hr.all(promises: Array>): Promise>; +ir.all(promises: Array>): Promise>; ``` -##### 1.11.2 代码示例 +**示例** ```typescript -// 创建多个 hr 请求实例 -const request1 = hr.get('https://www.example.com/data1'); -const request2 = hr.get('https://www.example.com/data2'); -const request3 = hr.get('https://www.example.com/data3'); +// 创建多个 ir 请求实例 +const request1 = ir.get('https://www.example.com/data1'); +const request2 = ir.get('https://www.example.com/data2'); +const request3 = ir.get('https://www.example.com/data3'); // 发送并发请求 -hr.all([request1, request2, request3]) +ir.all([request1, request2, request3]) .then(responseArray => { // 请求成功,处理每个请求的响应数据 responseArray.forEach(response => { @@ -492,29 +521,31 @@ hr.all([request1, request2, request3]) }); ``` -上述示例中,通过`hr.get`方法创建了三个`hr`请求实例,并将它们放入一个数组中。然后,将这个数组作为参数传递给`hr.all`方法,以同时发送这三个请求。在所有请求成功完成后,通过`responseArray`参数获取每个请求的响应数据,并进行处理。 +上述示例中,通过`ir.get`方法创建了三个`ir`请求实例,并将它们放入一个数组中。然后,将这个数组作为参数传递给`ir.all`方法,以同时发送这三个请求。在所有请求成功完成后,通过`responseArray`参数获取每个请求的响应数据,并进行处理。 -#### 1.12 hr.spread(callback) +### ir.spread(callback) -该接口是`horizon-request`库中的一个静态方法,用于将多个并发请求的响应数据传递给回调函数进行处理。通常配合`hr.all(iterable)`接口同时使用。 +**功能介绍** -##### 1.12.1 接口定义 +该接口是`inula-request`库中的一个静态方法,用于将多个并发请求的响应数据传递给回调函数进行处理。通常配合`ir.all(iterable)`接口同时使用。 + +**接口定义** ```typescript -hr.spread(callback: Callback): (arr: any[]) => T; +ir.spread(callback: Callback): (arr: any[]) => T; ``` -##### 1.12.2 代码示例 +**示例** ```typescript -// 创建多个 hr 请求实例 -const request1 = hr.get('https://www.example.com/data1'); -const request2 = hr.get('https://www.example.com/data2'); -const request3 = hr.get('https://www.example.com/data3'); +// 创建多个 ir 请求实例 +const request1 = ir.get('https://www.example.com/data1'); +const request2 = ir.get('https://www.example.com/data2'); +const request3 = ir.get('https://www.example.com/data3'); // 发送并发请求 -hr.all([request1, request2, request3]) - .then(hr.spread((response1, response2, response3) => { +ir.all([request1, request2, request3]) + .then(ir.spread((response1, response2, response3) => { // 请求成功,处理每个请求的响应数据 console.log(response1.data); console.log(response2.data); @@ -525,48 +556,50 @@ hr.all([request1, request2, request3]) }); ``` -上述示例中,通过`hr.get`方法创建了三个`hr`请求实例,并将它们放入一个数组中。然后,使用`hr.all`方法将这个数组作为参数传递给`hr.all`方法,以同时发送这三个请求。在`then`回调中,通过`hr.spread`方法将多个请求的响应数据传递给回调函数进行处理。在回调函数中,可以通过多个参数(`response1`、`response2`、`response3`)访问每个请求的响应数据。 +上述示例中,通过`ir.get`方法创建了三个`ir`请求实例,并将它们放入一个数组中。然后,使用`ir.all`方法将这个数组作为参数传递给`ir.all`方法,以同时发送这三个请求。在`then`回调中,通过`ir.spread`方法将多个请求的响应数据传递给回调函数进行处理。在回调函数中,可以通过多个参数(`response1`、`response2`、`response3`)访问每个请求的响应数据。 -#### 1.13 hr.create([config]) +### ir.create([config]) -该接口是`horizon-request`请求组件中的一个静态方法,用于创建一个独立的 hr 实例 。 +**功能介绍** -##### 1.13.1 接口定义 +该接口是`inula-request`请求组件中的一个静态方法,用于创建一个独立的 ir 实例 。 + +**接口定义** ```typescript -hr.create(config?: HrRequestConfig): HrInstance; +ir.create(config?: IrRequestConfig):IrInstance; ``` -其中`hr`实例类型`HrInstance`定义如下: +其中`ir`实例类型`IrInstance`定义如下: ```typescript -// Hr 类接口类型 -interface HrInterface { - request(url: string | Record, config?: HrRequestConfig): Promise>; +// Ir 类接口类型 +interface IrInterface { + request(url: string | Record, config?: IrRequestConfig): Promise>; - get(url: string, config?: HrRequestConfig): Promise>; + get(url: string, config?: IrRequestConfig): Promise>; - post(url: string, data?: any, config?: HrRequestConfig): Promise>; + post(url: string, data?: any, config?: IrRequestConfig): Promise>; - put(url: string, data?: any, config?: HrRequestConfig): Promise>; + put(url: string, data?: any, config?: IrRequestConfig): Promise>; - delete(url: string, config?: HrRequestConfig): Promise>; + delete(url: string, config?: IrRequestConfig): Promise>; - head(url: string, config?: HrRequestConfig): Promise>; + head(url: string, config?: IrRequestConfig): Promise>; - options(url: string, config?: HrRequestConfig): Promise>; + options(url: string, config?: IrRequestConfig): Promise>; } -// Hr 实例接口类型 -interface HrInstance extends HrInterface { - // Hr 类 - HorizonRequest: HrInterface; +// Ir 实例接口类型 +interface IrInstance extends IrInterface { + // Ir 类 + InulaRequest: IrInterface; - // 创建 Hr 实例 - create: (config?: HrRequestConfig) => HrInstance; + // 创建 Ir 实例 + create: (config?: IrRequestConfig) => IrInstance; // 使用内置的配置初始化实例属性 - defaults: HrRequestConfig; + defaults: IrRequestConfig; // 取消当前正在进行的请求 CancelToken: CancelTokenStatic; @@ -586,29 +619,29 @@ interface HrInstance extends HrInterface { // 封装多个 Promise 至数组,便于作为 all 传入参数 spread: (callback: Callback) => (arr: any[]) => T; - // horizonRequest 对象的默认实例 - default: HrInstance; + // InulaRequest 对象的默认实例 + default: IrInstance; CanceledError: typeof CancelError; - // HrError 错误 - HrError: typeof HrError; + // IrError 错误 + IrError: typeof IrError; - // 判断输入值是否为 HrError - isHrError: (avl: any) => boolean; + // 判断输入值是否为 IrError + isIrError: (avl: any) => boolean; - // HrHeaders 响应头 - HrHeaders: typeof HrHeaders; + // IrHeaders 响应头 + IrHeaders: typeof IrHeaders; - useHR: (url: string, config?: HrRequestConfig, options?: QueryOptions) => { data?: T; error?: any }; + useIR: (url: string, config?: IrRequestConfig, options?: QueryOptions) => { data?: T; error?: any }; } ``` -##### 1.13.2 代码示例 +**示例** ```typescript -// 创建一个独立的 hr 实例 -const instance = hr.create({ +// 创建一个独立的 ir 实例 +const instance = ir.create({ baseURL: 'https://www.example.com', timeout: 5000, headers: { @@ -627,45 +660,49 @@ instance.get('/data') }); ``` -上述示例中,使用`hr.create`方法创建了一个名为`instance`的独立`hr`实例。通过传递一个配置对象给`hr.create`方法,指定了实例的默认配置,包括基础URL、超时时间和请求头。然后,使用`instance`实例发送GET请求到`https://www.example.com/data`。在请求成功后,通过`response.data`访问服务器返回的数据。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 +上述示例中,使用`ir.create`方法创建了一个名为`instance`的独立`ir`实例。通过传递一个配置对象给`ir.create`方法,指定了实例的默认配置,包括基础URL、超时时间和请求头。然后,使用`instance`实例发送GET请求到`https://www.example.com/data`。在请求成功后,通过`response.data`访问服务器返回的数据。如果请求失败,将会捕获到`catch`块中的错误并进行处理。 -### 2 horizon-request 实例化方法 +## Inula-request 实例 API -通过1.13章节的`hr.create`方法可以创建一个独立的`hr`实例,您可以更改该实例的默认配置以便在同类场景中发送同类配置的网络请求,您可以创建多个实例以满足多场景下同类请求的发送。 +通过`ir.create`方法可以创建一个独立的`ir`实例,您可以更改该实例的默认配置以便在同类场景中发送同类配置的网络请求,您可以创建多个实例以满足多场景下同类请求的发送。 -方便起见,以下hr实例统一使用instance代替,实例对象上同样可以进行`request`、`get`、`post`、`delete`、`head`、`options`、`put`及`patch`请求的发送,其接口类型和使用方法与第一章节中各类请求方式一致。 +方便起见,以下ir实例统一使用instance代替,实例对象上同样可以进行`request`、`get`、`post`、`delete`、`head`、`options`、`put`及`patch`请求的发送,其接口类型和使用方法与第一章节中各类请求方式一致。 ```typescript -// 创建一个默认配置的 hr 实例 -const instance = hr.create(); +// 创建一个默认配置的 ir 实例 +const instance = ir.create(); // 实例对象上请求方法接口类型 -instance.get(url: string, config?: HrRequestConfig): Promise>; +instance.get(url: string, config?: IrRequestConfig): Promise>; -instance.get(url: string, config?: HrRequestConfig): Promise>; +instance.get(url: string, config?: IrRequestConfig): Promise>; -instance.post(url: string, data?: any, config?: HrRequestConfig): Promise>; +instance.post(url: string, data?: any, config?: IrRequestConfig): Promise>; -instance.delete(url: string, config?: HrRequestConfig): Promise>; +instance.delete(url: string, config?: IrRequestConfig): Promise>; -instance.head(url: string, config?: HrRequestConfig): Promise>; +instance.head(url: string, config?: IrRequestConfig): Promise>; -instance.options(url: string, config?: HrRequestConfig): Promise>; +instance.options(url: string, config?: IrRequestConfig): Promise>; -instance.put(url: string, data?: any, config?: HrRequestConfig): Promise>; +instance.put(url: string, data?: any, config?: IrRequestConfig): Promise>; -instance.patch(url: string, data?: any, config?: HrRequestConfig): Promise>; +instance.patch(url: string, data?: any, config?: IrRequestConfig): Promise>; ``` -### 3 请求配置参数 +## 请求配置全量参数 -`horizon-request`请求组件可以通过传入请求配置参数`config`自定义网络请求的行为,以便满足您在不同场景下的请求需求。 +### 请求配置参数使用 -#### 3.1 接口定义 +**功能介绍** + +`inula-request`请求组件可以通过传入请求配置参数`config`自定义网络请求的行为,以便满足您在不同场景下的请求需求。 + +**接口定义** ```typescript // 请求配置 -interface HrRequestConfig { +interface IrRequestConfig { url?: string; method?: Method; @@ -706,25 +743,23 @@ interface HrRequestConfig { } ``` -### 3.2 参数使用 +### url -#### 3.2.1 url 参数 - -##### 3.2.1.1 参数说明 +**参数说明** 该参数为请求的`URL`地址,类型为`string`。 该参数可以通过请求方法的第一个参数传入,也可以通过`config`配置对象的`url`字段传入。 -##### 3.2.1.2 代码示例 +**示例** ```typescript -hr({ +ir({ url: 'https://www.example.com' }) ``` -#### 3.2.2 method 参数 +### method -##### 3.2.2.1 参数说明 +**参数说明** 该参数为请求的`HTTP`方法。该参数在使用特定的请求方法时无需传入,在使用通用请求方法时通过`config`配置对象的`method`字段传入。 其类型定义如下: @@ -732,54 +767,54 @@ hr({ type Method = 'get' | 'GET' | 'delete' | 'DELETE' | 'head' | 'HEAD' | 'options' | 'OPTIONS' | 'post' | 'POST' | 'put' | 'PUT' | 'patch' | 'PATCH'; ``` -##### 3.2.2.2 代码示例 +**示例** ```typescript -hr('https://www.example.com', { +ir('https://www.example.com', { method: 'GET' }) ``` -#### 3.2.3 baseURL 参数 +### baseURL -##### 3.2.3.1 参数说明 +**参数说明** -该参数为请求的公共URL前缀,类型为string。该参数会自动拼接在传入的url之前,通常配合实例化请求使用,提供公共场景下的便利请求方式。 +该参数为请求的公共 `URL` 前缀,类型为 `string`。该参数会自动拼接在传入的 `URL` 之前,通常配合实例化请求使用,提供公共场景下的便利请求方式。 -##### 3.2.3.2 代码示例 +**示例** ```typescript -hr.get('/data', { +ir.get('/data', { baseURL: 'https://www.example.com' }) ``` -#### 3.2.4 headers 参数 +### headers -##### 3.2.4.1 参数说明 +**参数说明** 该参数为请求的自定义头信息,类型为`Record`。您可以根据自身需求在`config`中配置请求头信息,以满足不同场景的请求需求。 -##### 3.2.4.2 代码示例 +**示例** ```typescript -hr.get('https://www.example.com', { +ir.get('https://www.example.com', { headers: { 'Content-Type': 'application/json' } }) ``` -#### 3.2.5 params 参数 +### params -##### 3.2.5.1 参数说明 +**参数说明** 该参数为请求`URL`中的参数,类型为`Record`。该参数可以通过URL请求参数传入或通过`config`配置的`params`参数传入进而自动拼接到`URL`中。 -##### 3.2.5.2 代码示例 +**示例** ```typescript -hr.get('https://www.example.com', { +ir.get('https://www.example.com', { params: { id: 123, limit: 10, @@ -787,16 +822,16 @@ hr.get('https://www.example.com', { }) ``` -#### 3.2.6 data 参数 +### data -##### 3.2.6.1 参数说明 +**参数说明** -该参数为请求的数据体,类型为任意值。该参数为`post`、 `put`及`patch`请求所需要携带的数据,可以通过这些请求的第二个参数传入,也可以通过`config`配置的data字段传入。 +该参数为请求的数据体,类型为任意值。该参数为`POST`、 `PUT` 及 `PATCH` 请求所需要携带的数据,可以通过这些请求的第二个参数传入,也可以通过`config`配置的 `data` 字段传入。 -##### 3.2.6.2 代码示例 +**示例** ```typescript -hr.post('https://www.example.com/data', { +ir.post('https://www.example.com/data', { data: { name: 'Xiao Ming', age: 18, @@ -804,52 +839,52 @@ hr.post('https://www.example.com/data', { }) ``` -#### 3.2.7 timeout 参数 +### timeout -##### 3.2.7.1 参数说明 +**参数说明** -该参数为请求的超时时间(以毫秒为单位),类型为`number`。 请求过程中超过该配置时间`horizon-request`请求组件会自动中断请求并发送请求超时的错误消息。 +该参数为请求的超时时间(以毫秒为单位),类型为`number`。 请求过程中超过该配置时间,`inula-request`请求组件会自动中断请求并发送请求超时的错误消息。 -##### 3.2.7.2 代码示例 +**示例** ```typescript -hr.get('https://www.example.com', { +ir.get('https://www.example.com', { timeout: 5000 }) ``` -#### 3.2.8 timeoutErrorMessage 参数 +### timeoutErrorMessage -##### 3.2.8.1 参数说明 +**参数说明** 该参数为请求超时时的错误消息,类型为`string`,该参数需配合`timeout`参数同时使用 。 -##### 3.2.8.2 代码示例 +**示例** ```typescript -hr.get('https://www.example.com', { +ir.get('https://www.example.com', { timeout: 5000, timeoutErrorMessage: '请求超时,请重试。', }) ``` -#### 3.2.9 withCredentials 参数 +### withCredentials -##### 3.2.9.1 参数说明 +**参数说明** 该参数控制是否在跨域请求时包含凭据信息(如果存在),类型为`boolean`。默认情况下,该值为`false`,浏览器不会在跨域请求中发送凭据 。 -##### 3.2.9.2 代码示例 +**示例** ```typescript -hr.get('https://www.example.com', { +ir.get('https://www.example.com', { withCredentials: true }) ``` -#### 3.2.10 responseType 参数 +### responseType -##### 3.2.10.1 参数说明 +**参数说明** 该参数用于设置请求的响应类型,其类型定义如下: @@ -857,24 +892,24 @@ hr.get('https://www.example.com', { type ResponseType = 'text' | 'json' | 'blob' | 'arraybuffer'; ``` -##### 3.2.10.2 代码示例 +**示例** ```typescript -hr.get('https://www.example.com', { +ir.get('https://www.example.com', { responseType: 'json' }) ``` -#### 3.2.11 onUploadProgress 参数 +### onUploadProgress -##### 3.2.11.1 参数说明 +**参数说明** -该参数用于设置上传进度事件回调函数。 配置该参数后horizon-request请求组件将自动检测上传进度,并将进度信息作为参数传递给 `onUploadProgress` 回调函数。这个参数可以帮助您在 UI 中显示进度条或其他形式的进度指示器,以使用户能够了解文件上传的进展情况。 +该参数用于设置上传进度事件回调函数。 配置该参数后inula-request请求组件将自动检测上传进度,并将进度信息作为参数传递给 `onUploadProgress` 回调函数。这个参数可以帮助您在 UI 中显示进度条或其他形式的进度指示器,以使用户能够了解文件上传的进展情况。 -##### 3.2.11.2 代码示例 +**示例** ```typescript -hr.post('https://www.example.com/upload', formData, { +ir.post('https://www.example.com/upload', formData, { onUploadProgress: function(progressEvent) { // 计算上传进度的百分比 const percentCompleted = Math.round((progressEvent.loaded * 100) / progressEvent.total); @@ -885,16 +920,16 @@ hr.post('https://www.example.com/upload', formData, { }) ``` -#### 3.2.12 onDownloadProgress 参数 +### onDownloadProgress -##### 3.2.12.1 参数说明 +**参数说明** -该参数用于设置下载进度事件回调函数。 配置该参数后horizon-request请求组件将自动检测下载进度,并将进度信息作为参数传递给 `onDownloadProgress ` 回调函数。这个参数可以帮助您在 UI 中显示进度条或其他形式的进度指示器,以使用户能够了解文件下载的进展情况。 +该参数用于设置下载进度事件回调函数。 配置该参数后inula-request请求组件将自动检测下载进度,并将进度信息作为参数传递给 `onDownloadProgress ` 回调函数。这个参数可以帮助您在 UI 中显示进度条或其他形式的进度指示器,以使用户能够了解文件下载的进展情况。 -##### 3.2.12.2 参数说明 +**示例** ```typescript -hr.get('https://www.example.com/download', { +ir.get('https://www.example.com/download', { onDownloadProgress: function(progressEvent) { // 计算下载进度的百分比 var percentCompleted = Math.round((progressEvent.loaded * 100) / progressEvent.total); @@ -905,21 +940,21 @@ hr.get('https://www.example.com/download', { }) ``` -#### 3.2.13 cancelToken 参数(不推荐) +### cancelToken(不推荐) -##### 3.2.13.1 参数说明 +**参数说明** 该参数用于取消请求操作,它是一个特殊的标记对象,允许您在发送请求之前或请求过程中取消该请求。使用 `cancelToken` 参数可以避免不必要的网络请求,尤其是当您发送多个并发请求时。如果你想在某个请求完成之前取消其中一个或全部请求,便可以使用 `cancelToken`。 -##### 3.2.13.2 代码示例 +**示例** ```typescript // 首先创建一个 cancelToken 对象 -const CancelToken = hr.CancelToken; +const CancelToken = ir.CancelToken; const source = CancelToken.source(); // 将 cancelToken 对象作为配置对象的属性传递给请求组件 -hr.get('https://www.example.com/data', { +ir.get('https://www.example.com/data', { cancelToken: source.token }) @@ -927,13 +962,13 @@ hr.get('https://www.example.com/data', { source.cancel('请求被取消'); ``` -#### 3.2.14 signal 参数(推荐) +### signal(推荐) -##### 3.2.14.1 参数说明 +**参数说明** 该参数用于设置一个 `AbortSignal` 对象,用于取消正在进行的请求。`AbortSignal` 是 Web API 的一部分,在现代浏览器中提供了一种用于取消网络请求的机制。 -##### 3.2.14.2 代码示例 +**示例** ```typescript // 创建一个 AbortController 对象和对应的 AbortSignal @@ -941,12 +976,12 @@ const controller = new AbortController(); const signal = controller.signal; // 发起请求并传入 signal 参数 -hr.get('https://www.example.com/data', { signal }) +ir.get('https://www.example.com/data', { signal }) .then(response => { // 请求成功处理逻辑 }) .catch(error => { - if (hr.isCancel(error)) { + if (ir.isCancel(error)) { console.log('请求已取消', error.message); } else { console.log('请求发生错误', error.message); @@ -957,9 +992,9 @@ hr.get('https://www.example.com/data', { signal }) controller.abort(); ``` -#### 3.2.15 transitional 参数 +### transitional -##### 3.2.15.1 参数说明 +**参数说明** 该参数可以用来定义一些转换规则,其接口类型定义如下: @@ -976,54 +1011,57 @@ interface TransitionalOptions { } ``` -- `silentJSONParsing`用于配置解析 `JSON` 时是否静默处理错误,默认为`true`。配置为`true`时,如果发生 `JSON` 解析错误,将不会抛出异常,而是返回解析前的原始数据。 -- `forcedJSONParsing`用于控制是否强制解析 `JSON` 数据,默认为`true`。配置为`true`时,无论数据的 `MIME` 类型(如`text/plain`)是什么,都会尝试将其解析为 `JSON`。 -- `clarifyTimeoutError`用于控制是否在超时错误中提供更明确的错误信息,默认为`false`。配置为`true`时,将提供更具体的错误消息,指示发生的超时错误类型。 +- `silentJSONParsing`:用于配置解析 `JSON` 时是否静默处理错误,默认为`true`。配置为`true`时,如果发生 `JSON` 解析错误,将不会抛出异常,而是返回解析前的原始数据。 +- `forcedJSONParsing`:用于控制是否强制解析 `JSON` 数据,默认为`true`。配置为`true`时,无论数据的 `MIME` 类型(如`text/plain`)是什么,都会尝试将其解析为 `JSON`。 +- `clarifyTimeoutError`:用于控制是否在超时错误中提供更明确的错误信息,默认为`false`。配置为`true`时,将提供更具体的错误消息,指示发生的超时错误类型。 -##### 3.2.15.2 代码示例 +**示例** ```typescript -hr.get('https://www.example.com', { +ir.get('https://www.example.com', { transitional: { - silentJSONParsing: true, - forcedJSONParsing: false, - clarifyTimeoutError: false, + silentJSONParsing: true, + forcedJSONParsing: false, + clarifyTimeoutError: false, } }) ``` -### 4 拦截器 +## 拦截器 API -`horizon-request`请求组件的拦截器有两种类型:请求拦截器和响应拦截器。 +`inula-request`请求组件的拦截器有两种类型:请求拦截器和响应拦截器。 -#### 4.1 请求拦截器 +### 请求拦截器 -请求拦截器允许您在发送请求之前对其进行修改或添加特定配置。通过请求拦截器,您可以执行以下操作: +**功能介绍** -- 修改请求头信息,例如添加身份验证令牌。 -- 在每个请求中添加通用参数。 -- 对请求体进行转换。 -- 拦截请求错误并进行相应处理。 +请求拦截器允许您在发送请求之前对其进行修改或添加特定配置。通过请求拦截器,您可以执行以下操作(任意一项/几项/其他操作): -##### 4.1.1 接口定义 +> - 修改请求头信息,例如添加身份验证令牌。 +> - 在每个请求中添加通用参数。 +> - 对请求体进行转换。 +> - 拦截请求错误并进行相应处理。 +> - ... + +**接口定义** ```typescript -hr.interceptors.request.use( - fulfilled?: FulfilledFn, +ir.interceptors.request.use( + fulfilled?: FulfilledFn, rejected?: RejectedFn, - options?: { synchronous?: boolean; runWhen?: (value: HrRequestConfig) => boolean } - ): number; + options?: { synchronous?: boolean; runWhen?: (value: IrRequestConfig) => boolean } +): number; type FulfilledFn = (value: T) => T | Promise; type RejectedFn = (error: any) => any; ``` -- `fulfilled`为请求成功的回调函数,在请求成功时被调用。它接收一个参数类型为 `HrRequestConfig`的配置`config`,表示已经发送请求的配置。 -- `rejected`为请求失败的回调函数,用于处理请求失败的情况 。 -- `options` 为拦截器的配置参数,用于配置拦截器的行为 。其中`synchronous` 为一个布尔值,指示是否同步地运行拦截器 ;`runWhen` 用于确定是否应该运行拦截器 。 +- `fulfilled`:为请求成功的回调函数,在请求成功时被调用。它接收一个参数类型为 `IrRequestConfig`的配置`config`,表示已经发送请求的配置。 +- `rejected`:为请求失败的回调函数,用于处理请求失败的情况 。 +- `options` :为拦截器的配置参数,用于配置拦截器的行为 。其中`synchronous` 为一个布尔值,指示是否同步地运行拦截器 ;`runWhen` 用于确定是否应该运行拦截器 。 - 返回值为一个数字 ,表示拦截器的唯一标识符,这个标识符可以用于后续操作,如移除拦截器。 -##### 4.1.2 代码示例 +**示例** ```typescript // 定义一个成功回调函数 @@ -1046,14 +1084,14 @@ const options = { }; // 注册拦截器 -const interceptorId = hr.interceptors.request.use( +const interceptorId = ir.interceptors.request.use( fulfilledCallback, rejectedCallback, options, ); // 发起请求 -hr.get('https://www.example.com') +ir.get('https://www.example.com') .then((response) => { console.log('响应数据:', response.data); }) @@ -1062,30 +1100,42 @@ hr.get('https://www.example.com') }); // 取消拦截器 -hr.interceptors.request.eject(interceptorId); +ir.interceptors.request.eject(interceptorId); ``` -#### 4.2 响应拦截器 +在上面示例中,定义了一个成功的回调函数和一个拒绝的回调函数,并配置了 `synchronous` 为 `true` 同步执行拦截器,配置了 `runWhen` 只有在请求方法为 `GET` 时才运行拦截器。将请求拦截器参数传入拦截器接口中,会返回一个拦截器 `id` ,可以用于后续注销。配置拦截器后正常发送请求,在请求发送到服务端之前会进入请求拦截器逻辑,您可以通过请求拦截器更加个性化定制您的请求。 -##### 4.2.1 接口定义 +### 响应拦截器 + +**功能介绍** + +请求拦截器允许您在发送请求之前对其进行修改或添加特定配置。通过请求拦截器,您可以执行以下操作(任意一项/几项/其他操作): + +> - 修改响应头。 +> - 在每个响应体添加额外内容。 +> - 对响应体进行转换。 +> - 拦截错误响应,并进行相应处理。 +> - ... + +**接口定义** ```typescript -hr.interceptors.response.use( - fulfilled?: FulfilledFn>, +ir.interceptors.response.use( + fulfilled?: FulfilledFn>, rejected?: RejectedFn, - options?: { synchronous?: boolean; runWhen?: (value: HrResponse) => boolean } - ): number; + options?: { synchronous?: boolean; runWhen?: (value: IrResponse) => boolean } +): number; type FulfilledFn = (value: T) => T | Promise; type RejectedFn = (error: any) => any; ``` -- `fulfilled`为请求成功的回调函数,在请求成功时被调用。它接收一个参数类型为 `HrResponse`的请求响应`response`,表示获取的请求响应。 -- `rejected`为请求失败的回调函数,用于处理请求失败的情况 。 -- `options` 为拦截器的配置参数,用于配置拦截器的行为 。其中`synchronous` 为一个布尔值,指示是否同步地运行拦截器 ;`runWhen` 用于确定是否应该运行拦截器 。 +- `fulfilled`:为请求成功的回调函数,在请求成功时被调用。它接收一个参数类型为 `IrResponse`的请求响应`response`,表示获取的请求响应。 +- `rejected`:为请求失败的回调函数,用于处理请求失败的情况 。 +- `options` :为拦截器的配置参数,用于配置拦截器的行为 。其中`synchronous` 为一个布尔值,指示是否同步地运行拦截器 ;`runWhen` 用于确定是否应该运行拦截器 。 - 返回值为一个数字 ,表示拦截器的唯一标识符,这个标识符可以用于后续操作,如移除拦截器。 -##### 4.2.2 代码示例 +**示例** ```typescript // 定义成功处理函数 @@ -1107,15 +1157,15 @@ const options = { runWhen: (config) => config.method === 'GET', // 只在请求方法为GET时运行拦截器 }; -// 使用hr.interceptors.response.use方法 -const interceptorId = hr.interceptors.response.use( +// 使用ir.interceptors.response.use方法 +const interceptorId = ir.interceptors.response.use( fulfilledHandler, rejectedHandler, options, ); // 发起请求 -hr.get('https://www.example.com') +ir.get('https://www.example.com') .then((response) => { console.log('请求结果:', response); }) @@ -1124,39 +1174,43 @@ hr.get('https://www.example.com') }); // 取消拦截器 -hr.interceptors.response.eject(interceptorId); +ir.interceptors.response.eject(interceptorId); ``` -### 5 请求错误 +在上面示例中,定义了一个成功的回调函数和一个拒绝的回调函数,并配置了 `synchronous` 为 `true` 同步执行拦截器,配置了 `runWhen` 只有在请求方法为 `GET` 时才运行拦截器。将响应拦截器参数传入拦截器接口中,会返回一个拦截器 `id` ,可以用于后续注销。配置拦截器后正常发送请求,在请求被服务端响应后会进入响应拦截器逻辑,您可以通过响应拦截器更加个性化定制您的请求。 -`horizon-request`请求组件提供了`HrError`类用于实例化请求错误对象,其包含了与请求相关的详细信息,以帮助开发者识别和处理错误。 +## 请求错误 -#### 5.1 接口定义 +**功能介绍** + +`inula-request`请求组件提供了`IrError`类用于实例化请求错误对象,其包含了与请求相关的详细信息,以帮助开发者识别和处理错误。 + +**接口定义** ```typescript -class HrError extends Error implements HrErrorInterface; +class IrError extends Error implements IrErrorInterface; -interface HrErrorInterface { +interface IrErrorInterface { // 产生错误的请求配置对象 - config?: HrRequestConfig; + config?: IrRequestConfig; // 表示请求错误的字符串代码。例如,"ECONNABORTED"表示连接被中止。 code?: string; // 产生错误的原始请求实例。 - request?: HrInstance; + request?: IrInstance; // 包含错误响应的响应实例。如果请求成功完成,但服务器返回错误状态码(例如404或500),则此属性存在。 - response?: HrResponse; + response?: IrResponse; } ``` -#### 5.2 代码示例 +**示例** ```typescript -hr.get('https://www.example.com/users') +ir.get('https://www.example.com/users') .then(response => { // 处理成功响应 console.log(response.data); }) - .catch((error: HrError) => { + .catch((error: IrError) => { if (error.response) { // 请求已发出,但服务器响应状态码不在 2xx 范围内 console.log(error.response.data); @@ -1173,23 +1227,25 @@ hr.get('https://www.example.com/users') }); ``` -- 在上面的示例中,使用hr发送一个GET请求到`https://www.example.com/users`。如果请求成功,打印出返回的数据;如果请求失败,捕获`HrError`并根据错误的类型进行处理。 -- 在`catch`块中,可以通过`error.response`访问到服务器返回的响应信息。如果`error.response`存在,则意味着服务器有响应,但状态码不在2xx范围内。我们可以访问`error.response.data`获取服务器返回的数据,`error.response.status`获取状态码,以及`error.response.headers`获取响应头信息。 +- 在上面的示例中,使用ir发送一个GET请求到`https://www.example.com/users`。如果请求成功,打印出返回的数据;如果请求失败,捕获`IrError`并根据错误的类型进行处理。 +- 在`catch`块中,可以通过`error.response`访问到服务器返回的响应信息。如果`error.response`存在,则意味着服务器有响应,但状态码不在2xx范围内。可以访问`error.response.data`获取服务器返回的数据,`error.response.status`获取状态码,以及`error.response.headers`获取响应头信息。 - 如果`error.response`不存在,而`error.request`存在,则表示请求已发送但未收到响应。在这种情况下,可以直接访问`error.request`获取请求对象。 - 如果以上两种情况都不满足,说明在设置请求时出现了错误,或者其他一些未知的错误,可以通过`error.message`打印错误信息。 -### 6 请求取消 +## 请求取消 -在`horizon-request`请求组件中,提供两种取消请求方式:`cancelToken`和`AbortController`。其中`cancelToken`的方式已过时,推荐使用`AbortController`的取消请求方式。具体使用方式参见3.2.13和3.2.14章节。 +在`inula-request`请求组件中,提供两种取消请求方式:`cancelToken`和`AbortController`。其中`cancelToken`的方式已过时,推荐使用`AbortController`的取消请求方式。具体使用方式参见 [cancelToken (不推荐)](#cancelToken(不推荐)) 和 [signal(推荐)](#signal(推荐))章节。 -### 7 请求实时数据流 +## 请求实时刷新 API -`horizon-reques`t请求组件提供支持动态轮询的实时数据流能力,帮助您在使用`horizon`框架进行页面开发时拥有更加便捷的请求体验! +**功能介绍** -#### 7.1 接口定义 +`Inula-request`请求组件提供支持动态轮询的实时数据刷新能力,帮助您在使用`InulaJS`框架进行页面开发时拥有更加便捷的请求体验! + +**接口定义** ```typescript -hr.useHR: (url: string, config?: HrRequestConfig, options?: QueryOptions) => {data?: T, error?: any} +ir.useIR: (url: string, config?: IrRequestConfig, options?: QueryOptions) => {data?: T, error?: any} // 轮询查询配置 轮询间隔(毫秒) interface QueryOptions { @@ -1198,7 +1254,7 @@ interface QueryOptions { enablePollingOptimization?: boolean; // 配置动态轮询策略后生效 limitation?: Limitation; - // 动态轮询策略分析历史数据容量,默认100 + // 动态轮询策略分析历史查询容量,默认100 capacity?: number; // 动态轮询策略窗口大小,默认5 windowSize?: number; @@ -1210,21 +1266,21 @@ interface Limitation { } ``` -`url`和`config`参数和`horizon-request`请求组件接口参数一致,用于配置网络请求。 +`url`和`config`参数和`inula-request`请求组件接口参数一致,用于配置网络请求。 `options`参数为动态轮询配置参数,其中: -- 配置`pollingInterval`参数后将开启实时数据流功能,`horizon-request`请求组件会根据`pollingInterval`的间隔轮询请求服务端,当请求的服务端数据发生改变时会通知组件拿到最新数据并重新渲染; -- `enablePollingOptimization`参数用于开启动态轮询策略,该参数配置为`true`时,会启动动态轮询策略,`horizon-request`请求组件将分析历史请求数据,动态更新轮询间隔(若服务器数据变化频繁则会缩短轮询间隔时间,反之增加轮询间隔时间,最大保证用户体验一致性的同时减缓服务器压力),动态轮询间隔会有一个默认的最大间隔时间`60000ms`和最小间隔时间`100ms`; +- 配置`pollingInterval`参数后将开启实时数据刷新功能,`inula-request`请求组件会根据`pollingInterval`的间隔轮询请求服务端,当请求的服务端数据发生改变时会通知组件拿到最新数据并重新渲染; +- `enablePollingOptimization`参数用于开启动态轮询策略,该参数配置为`true`时,会启动动态轮询策略,`inula-request`请求组件将分析历史请求数据,动态更新轮询间隔(若服务器数据变化频繁则会缩短轮询间隔时间,反之增加轮询间隔时间,最大保证用户体验一致性的同时减缓服务器压力),动态轮询间隔会有一个默认的最大间隔时间`60000ms`和最小间隔时间`100ms`; - 您也可以通过`limitation`中的`maxInterval`参数来配置最大间隔时间,`minInterval`参数配置最小间隔时间; -- 您也可以自定义动态轮询策略的配置参数,通过`capacity`参数来设置分析的历史数据容量,通过`windowSize`设置动态轮询策略滑动窗口大小。 +- 您也可以自定义动态轮询策略的配置参数,通过`capacity`参数来设置分析的历史数据容量,组件内部会通过您设置的数据容量分析数据更新的间隔趋势,以更新当前的轮询时间。通过`windowSize`设置动态轮询策略滑动窗口大小,该参数用于帮助用户更加细粒度控制分析数据变化趋势的梯度范围,以提供更加精准的轮询间隔设置。 -通过以上参数,您可以更加灵活的配置实时数据流特性以满足您在不同场景下的使用需求。 +通过以上参数,您可以更加灵活的配置实时数据刷新特性以满足您在不同场景下的使用需求。 -#### 7.2 代码示例 +**示例** ```typescript -import { useHR } from 'horizon-request'; +import { useIR } from 'inula-request'; const App = () => { const options = { @@ -1232,7 +1288,7 @@ const App = () => { enablePollingOptimization: true, limitation: {minInterval: 500, maxInterval: 4000} }; - const { data, error } = useHR('https://www.example.com', null, options); + const { data, error } = useIR('https://www.example.com', null, options); return (
@@ -1242,4 +1298,4 @@ const App = () => { } ``` -在上面的示例中,`App`组件使用`useHR`获取了服务端的实时数据,并配置了动态轮询策略。若请求成功则会将服务端数据显示在`pre`标签中,当服务器数据发生变化,`pre`标签中也会同步刷新最新数据,当请求发生错误,将会显示错误信息。 +在上面的示例中,`App`组件使用`useIR`获取了服务端的最新数据,并配置了动态轮询策略。若请求成功则会将服务端数据显示在`pre`标签中,当服务器数据发生变化,`pre`标签中也会同步刷新最新数据,当请求发生错误,将会显示错误信息。 diff --git a/packages/horizon-request/examples/cancelRequest/cancelRequestTest.html b/packages/horizon-request/examples/cancelRequest/cancelRequestTest.html index 9f754b86..85c97541 100644 --- a/packages/horizon-request/examples/cancelRequest/cancelRequestTest.html +++ b/packages/horizon-request/examples/cancelRequest/cancelRequestTest.html @@ -24,9 +24,9 @@ sendRequestButton.addEventListener('click', function() { message.innerHTML = ''; - cancelTokenSource = horizonRequest.CancelToken.source(); + cancelTokenSource = inulaRequest.CancelToken.source(); - horizonRequest.get('http://localhost:3001/data', { + inulaRequest.get('http://localhost:3001/data', { cancelToken: cancelTokenSource.token }).then(function(response) { message.innerHTML = '请求成功: ' + JSON.stringify(response.data, null, 2); @@ -36,15 +36,15 @@ }); cancelRequestButton.addEventListener('click', function () { - const CancelToken = horizonRequest.CancelToken; + const CancelToken = inulaRequest.CancelToken; const source = CancelToken.source(); - horizonRequest.get('http://localhost:3001/data', { + inulaRequest.get('http://localhost:3001/data', { cancelToken: source.token }).then(function(response) { console.log(response.data); }).catch(function(error) { - if (horizonRequest.isCancel(error)) { + if (inulaRequest.isCancel(error)) { message.innerHTML = '请求已被取消:' + error.message; } else { message.innerHTML = '请求出错:' + error.message; diff --git a/packages/horizon-request/examples/interceptor/interceptorTest.html b/packages/horizon-request/examples/interceptor/interceptorTest.html index 0fea5dac..14207439 100644 --- a/packages/horizon-request/examples/interceptor/interceptorTest.html +++ b/packages/horizon-request/examples/interceptor/interceptorTest.html @@ -3,11 +3,11 @@ - Horizon Request Interceptor Test + Inula Request Interceptor Test -
Horizon Request interceptor Test
+
Inula Request interceptor Test

使用拦截器:

响应状态码:

@@ -89,7 +89,7 @@ // 不使用拦截器的请求 document.getElementById('sendRequestWithoutInterceptor').addEventListener('click', function () { - horizonRequest.get('http://localhost:3001/') + inulaRequest.get('http://localhost:3001/') .then(function (response) { document.getElementById('responseStatusWithoutInterceptor').textContent = response.status; document.getElementById('responseDataWithoutInterceptor').textContent = JSON.stringify(response.data, null, 2); diff --git a/packages/horizon-request/examples/request/requestTest.html b/packages/horizon-request/examples/request/requestTest.html index 7bcfee1f..57415222 100644 --- a/packages/horizon-request/examples/request/requestTest.html +++ b/packages/horizon-request/examples/request/requestTest.html @@ -2,11 +2,11 @@ - Horizon Request API Test + Inula Request API Test -
Horizon Request API Test
+
Inula Request API Test

Request

@@ -85,8 +85,8 @@ const resetButton = document.getElementById('resetButton'); queryButton.addEventListener('click', function () { - const inulaRequest = inulaRequest.create(); - inulaRequest.request('http://localhost:3001/', {method: 'GET', data: {}}) + const irInstance = inulaRequest.create(); + irInstance.request('http://localhost:3001/', {method: 'GET', data: {}}) .then(function (response) { requestResult.innerHTML = JSON.stringify(response.data, null, 2); }) @@ -189,7 +189,7 @@ const formData = new FormData(); formData.append('file', file); - horizonRequest.post('http://localhost:3001/', formData, { + inulaRequest.post('http://localhost:3001/', formData, { onUploadProgress: function (progressEvent) { const loaded = progressEvent.loaded; const total = progressEvent.total; diff --git a/packages/horizon-request/examples/server/serverTest.mjs b/packages/horizon-request/examples/server/serverTest.mjs index 307dd671..e71f7fe4 100644 --- a/packages/horizon-request/examples/server/serverTest.mjs +++ b/packages/horizon-request/examples/server/serverTest.mjs @@ -23,12 +23,12 @@ app.use(cors(corsOptions)); // 处理 GET 请求 app.get('/', (req, res) => { - res.send('Hello Horizon Request!'); + res.send('Hello Inula Request!'); }) app.get('/data', (req, res) => { const data = { - message: 'Hello Horizon Request!', + message: 'Hello Inula Request!', }; res.setHeader('Content-Type', 'application/json'); @@ -37,7 +37,7 @@ app.get('/data', (req, res) => { }); app.get('/download', (req, res) => { - const filePath = 'D:\\code\\MRcode\\Horizon-Request\\examples\\request\\downloadTest.html'; + const filePath = 'D:\\code\\MRcode\\inula-Request\\examples\\request\\downloadTest.html'; const fileName = 'downloadTest.html'; const fileSize = fs.statSync(filePath).size; diff --git a/packages/horizon-request/rollup.config.js b/packages/horizon-request/rollup.config.js index 3dce9328..c864ed34 100644 --- a/packages/horizon-request/rollup.config.js +++ b/packages/horizon-request/rollup.config.js @@ -7,10 +7,10 @@ import { babel } from '@rollup/plugin-babel'; export default { input: './index.ts', output: { - file: 'dist/horizonRequest.js', + file: 'dist/inulaRequest.js', format: 'umd', exports: 'named', - name: 'horizonRequest', + name: 'inulaRequest', sourcemap: false, }, plugins: [ diff --git a/packages/horizon-request/src/request/processUploadProgress.ts b/packages/horizon-request/src/request/processUploadProgress.ts index 5b323767..25f3e35e 100644 --- a/packages/horizon-request/src/request/processUploadProgress.ts +++ b/packages/horizon-request/src/request/processUploadProgress.ts @@ -12,11 +12,17 @@ function processUploadProgress( ) { if (onUploadProgress) { let totalBytesToUpload = 0; // 上传的总字节数 - data.forEach(value => { - if (value instanceof Blob) { - totalBytesToUpload += value.size; - } - }); + + if (data instanceof File) { + totalBytesToUpload = data.size; + } + if (data instanceof FormData) { + data.forEach(value => { + if (value instanceof Blob) { + totalBytesToUpload += value.size; + } + }); + } const handleUploadProgress = () => { const xhr = new XMLHttpRequest(); diff --git a/packages/horizon-request/webpack.config.js b/packages/horizon-request/webpack.config.js index 1b92c4e7..56813b11 100644 --- a/packages/horizon-request/webpack.config.js +++ b/packages/horizon-request/webpack.config.js @@ -4,7 +4,7 @@ const path = require('path'); // webpack配置信息 module.exports = { // 指定入口文件 - entry: './src/horizonRequest.ts', + entry: './src/inulaRequest.ts', // 指定打包文件信息 output: { @@ -12,7 +12,7 @@ module.exports = { path: path.resolve(__dirname, 'dist'), library: 'myLibrary', libraryTarget: 'umd', - filename: 'horizonRequest.js', + filename: 'inulaRequest.js', }, // 指定打包时使用的模块