diff --git a/docs/pages/advanced/adapter.md b/docs/pages/advanced/adapter.md index 8d65fd7..c0111ff 100644 --- a/docs/pages/advanced/adapter.md +++ b/docs/pages/advanced/adapter.md @@ -270,6 +270,7 @@ import axios from 'axios-miniprogram'; axios.defaults.adapter = axios.createAdapter({ request: uni.request, upload: (config) => { + // 其实差异只有一点点,抹平可以很轻易~ const { // 需要上传的文件列表 // App、H5( 2.6.15+) diff --git a/docs/pages/advanced/fork.md b/docs/pages/advanced/fork.md index ad6fba0..149e943 100644 --- a/docs/pages/advanced/fork.md +++ b/docs/pages/advanced/fork.md @@ -5,24 +5,22 @@ title: 派生领域 # {{ $frontmatter.title }} ::: tip {{ $frontmatter.title }} -派生新的领域管理 `URL` 简化请求。 - -`defaults` 和派生 `domain` 时传入的 `config` 将会按优先级合并成 `domain.defaults`。 - -如果 `config.baseURL` 是一个相对地址,将会和 `defaults.baseURL` 组合成完整的服务端地址。 - -[合并策略](/basics/defaults#合并策略) +派生新的领域简化 `URL`。 ::: ## 派生领域 -可以传入 config 派生领域。 +可以基于 `axios` 派生领域,配置项 `baseURL` 传相对地址时会和 `axios.defaults.baseURL` 一起组合成完整的服务端地址。 + +全局默认配置 `axios.defaults` 和派生领域时传入的配置 `config` 将会按优先级[合并](/basics/defaults#配置合并策略)成领域默认配置 `domain.defaults`。 ```ts import axios from 'axios-miniprogram'; axios.defaults.baseURL = 'https://api.com'; +// 相对地址会进行组合 +// baseURL 最终结果为 https://api.com/uesr const domain = axios.fork({ baseURL: 'user', headers: { @@ -36,17 +34,8 @@ const domain = axios.fork({ timeout: 1000, }); -// 请求的服务端地址 https://api.com/uesr -domain.get('/'); -``` - -也可以使用绝对路径 `config.baseURL` 派生领域。 - -```ts -import axios from 'axios-miniprogram'; - -axios.defaults.baseURL = 'https://api.com'; - +// 绝对地址会直接使用 +// baseURL 最终结果为 https://api2.com/user const domain = axios.fork({ baseURL: 'https://api2.com/user', headers: { @@ -59,14 +48,11 @@ const domain = axios.fork({ }, timeout: 1000, }); - -// 请求的服务端地址 https://api2.com/uesr -domain.get('/'); ``` ## 默认配置 -可以设置 `domain.defaults` 属性默认值。 +可以设置配置项默认值。 ```ts import axios from 'axios-miniprogram'; @@ -83,13 +69,87 @@ domain.defaults.timeout = 1000; ## 拦截器 -基于 `axios` 派生出的 `domain`,在发送请求时会使用 `axios` 的拦截器。 +可以使用父级的拦截器,但不支持为领域单独添加拦截器。 -基于 `instance` 派生出的 `domain`,在发送请求时会使用 `instance` 的拦截器。 +基于 axios 派生领域。 -目前上不支持为 `domain` 单独添加拦截器。 +```ts +import axios from 'axios-miniprogram'; -## 使用 +// 请求拦截器 +axios.interceptors.request.use( + function (config) { + // 在发送请求之前做些什么 + return config; + }, + function (error) { + // 对请求错误做些什么 + return Promise.reject(error); + }, +); + +// 响应拦截器 +axios.interceptors.response.use( + function (response) { + // 在 then 之前做些什么 + return response; + }, + function (error) { + // 在 catch 之前做些什么 + return Promise.reject(error); + }, +); + +const domain = axios.fork({ + baseURL: 'test', +}); + +// 发送请求时会使用 axios 的请求拦截器和响应拦截器 +domain.get('/'); +``` + +基于实例派生领域。 + +```ts +import axios from 'axios-miniprogram'; + +const instance = axios.create({ + baseURL: 'https://api.com', +}); + +// 请求拦截器 +instance.interceptors.request.use( + function (config) { + // 在发送请求之前做些什么 + return config; + }, + function (error) { + // 对请求错误做些什么 + return Promise.reject(error); + }, +); + +// 响应拦截器 +instance.interceptors.response.use( + function (response) { + // 在 then 之前做些什么 + return response; + }, + function (error) { + // 在 catch 之前做些什么 + return Promise.reject(error); + }, +); + +const domain = instance.fork({ + baseURL: 'test', +}); + +// 发送请求时会使用 instance 的请求拦截器和响应拦截器 +domain.get('/'); +``` + +## 使用方式 可以使用请求方法发送请求。 diff --git a/docs/pages/advanced/instance.md b/docs/pages/advanced/instance.md index 829504e..f59152c 100644 --- a/docs/pages/advanced/instance.md +++ b/docs/pages/advanced/instance.md @@ -5,22 +5,21 @@ title: 创建实例 # {{ $frontmatter.title }} ::: tip {{ $frontmatter.title }} -创建全新的 `instance` 实例。 +创建新的实例。 -`defaults` 和创建 `instance` 时传入的 `config` 将会按优先级合并成 `instance.defaults` 。 - -[合并策略](/basics/defaults#合并策略) ::: ## 创建实例 -可以使用 `axios.create(config)` 创建 `instance`。 +可以使用 `axios.create(config)` 创建新的实例。 + +全局默认配置 `axios.defaults` 和创建实例时传入的配置 `config` 将会按优先级[合并](/basics/defaults#配置合并策略)成实例默认配置 `instance.defaults`。 ```ts import axios from 'axios-miniprogram'; const instance = axios.create({ - baseURL: 'https"//api2.com', + baseURL: 'https://api2.com', headers: { common: { ['Content-Type']: 'application/json', @@ -35,13 +34,13 @@ const instance = axios.create({ ## 默认配置 -可以设置 `instance.defaults` 属性默认值。 +可以设置配置项默认值。 ```ts import axios from 'axios-miniprogram'; const instance = axios.create({ - baseURL: 'https"//api2.com', + baseURL: 'https://api2.com', }); instance.defaults.headers.common['Content-Type'] = 'application/json'; @@ -50,13 +49,13 @@ instance.defaults.timeout = 1000; ## 添加拦截器 -可以在 `instance`上添加 [请求拦截器](/advanced/request-interceptor) 和 [响应拦截器](/advanced/response-interceptor)。 +可以添加实例的[请求拦截器](/advanced/request-interceptor)和[响应拦截器](/advanced/response-interceptor)。 ```ts import axios from 'axios-miniprogram'; const instance = axios.create({ - baseURL: 'https"//api2.com', + baseURL: 'https://api2.com', }); // 请求拦截器 @@ -86,13 +85,15 @@ instance.interceptors.response.use( ## 派生领域 -可以基于 `instance` [派生领域](/advanced/fork)。 +可以基于实例[派生领域](/advanced/fork)。 + +实例默认配置 `instance.defaults` 和派生领域时传入的配置 `config` 将会按优先级[合并](/basics/defaults#配置合并策略)成领域默认配置 `domain.defaults`。 ```ts import axios from 'axios-miniprogram'; const instance = axios.create({ - baseURL: 'https"//api2.com', + baseURL: 'https://api2.com', }); const domain = instance.fork({ @@ -109,7 +110,7 @@ domain.get('/'); ```ts const instance = axios.create({ - baseURL: 'https"//api2.com', + baseURL: 'https://api2.com', }); instance('test') diff --git a/docs/pages/basics/cancel.md b/docs/pages/basics/cancel.md index bedd87a..96bf66f 100644 --- a/docs/pages/basics/cancel.md +++ b/docs/pages/basics/cancel.md @@ -35,7 +35,7 @@ cancel('request canceled'); ## 工厂方法 -也可以用 `CancelToken.source` 工厂方法创建 `CancelToken` 实例用来取消请求。 +可以用 `CancelToken.source` 工厂方法创建 `CancelToken` 实例用来取消请求。 ```ts import axios from 'axios-miniprogram'; @@ -57,7 +57,7 @@ cancel('request canceled'); ## 判断取消请求 -也可以用 `axios.isCancel` 判断请求错误是否来自取消请求,从而做出相应的处理。 +可以判断请求错误是否来自取消请求,从而做出相应的处理。 ```ts import axios from 'axios-miniprogram'; @@ -70,6 +70,7 @@ axios('https://api.com/test', { // 成功之后做些什么 }) .catch((error) => { + // 判断取消请求 if (axios.isCancel(error)) { console.log(error, '请求已被取消'); } diff --git a/docs/pages/basics/config.md b/docs/pages/basics/config.md index d431f34..62a16d5 100644 --- a/docs/pages/basics/config.md +++ b/docs/pages/basics/config.md @@ -8,9 +8,9 @@ title: 请求配置 用于自定义请求行为。 ::: -## 通用属性 +## 通用配置项 -可以设置这些属性。 +可以设置这些配置项。 ```ts import axios from 'axios-miniprogram'; @@ -103,9 +103,9 @@ axios({ }); ``` -## 平台属性 +## 平台配置项 -也可以设置平台特有属性,具体情况取决于平台特性。 +可以设置平台特有的配置项,具体情况取决于平台特性。 微信小程序示例: @@ -144,11 +144,11 @@ axios({ 想要了解更多请自行参阅对应平台文档。 -## 自定义属性 +## 自定义配置项 -也可以设置自定义属性,从而实现一些自定义功能。 +可以设置自定义配置项,从而实现一些自定义功能。 -自定义属性可以根据需要随意设置。 +自定义配置项可以根据需要随意设置。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/defaults.md b/docs/pages/basics/defaults.md index f1e75d5..a024fd1 100644 --- a/docs/pages/basics/defaults.md +++ b/docs/pages/basics/defaults.md @@ -5,14 +5,14 @@ title: 默认配置 # {{ $frontmatter.title }} ::: tip {{ $frontmatter.title }} -默认配置 `defaults` 会作用于每个请求。 +用于设置作用于每个请求的配置项默认值。 -[合并策略](/basics/defaults#合并策略) +[配置合并策略](/basics/defaults#配置合并策略) ::: ## 默认值 -在不更改 `defaults` 的情况下,它依然会存在一些默认值,在 [defaults.ts](https://github.com/zjx0905/axios-miniprogram/blob/main/src/defaults.ts) 中定义,大概长下面这样。 +在不更改默认配置的情况下,它依然会存在一些默认值,在 [defaults.ts](https://github.com/zjx0905/axios-miniprogram/blob/main/src/defaults.ts) 中定义,大概长下面这样。 ```ts { @@ -53,9 +53,9 @@ title: 默认配置 } ``` -## 设置属性 +## 设置配置项 -可以给属性设置默认值。 +可以设置配置项默认值。 列举部分示例: @@ -91,9 +91,9 @@ axios.defaults.onUploadProgress = (event) => { }; ``` -## 设置平台属性 +## 设置平台配置项 -也可以给平台特有属性设置默认值,具体情况取决于平台特性。 +可以设置平台特有配置项默认值,具体情况取决于平台特性。 微信小程序示例: @@ -121,15 +121,17 @@ axios.defaults.forceCellularNetwork = false; 想要了解更多请自行参阅对应平台文档。 -## 设置自定义属性 +## 设置自定义配置项 -也可以给自定义属性设置默认值,从而实现一些自定义功能。 +可以设置自定义配置项默认值。 ```ts import axios from 'axios-miniprogram'; // 出错时显示错误信息 axios.defaults.showError = true; +// 请求时自动 loading +axios.defaults.showLoading = true; // 错误处理 axios.defaults.errorHandler = (error) => { @@ -143,9 +145,6 @@ axios.defaults.errorHandler = (error) => { } }; -// 请求时自动 loading -axios.defaults.showLoading = true; - // 请求拦截器 axios.interceptors.request.use((config) => { // 自动显示 loading @@ -165,10 +164,10 @@ axios.interceptors.response.use((response) => { }); ``` -## 合并策略 +## 配置合并策略 -`defaults` 和 `config` 将会按优先级进行合并。 +默认配置和请求配置将会按优先级进行合并。 -其中 `url/method/data/upload/download` 只从 `config` 取值,`headers/params` 进行深度合并,其余属性则会优先从 `config` 取值。 +其中 `url`、`method`、`data`、`upload`、`download` 只从 `config` 取值,`headers`、`params` 会进行深度合并,其余属性则会优先从 `config` 取值。 -具体合并策略请参阅 [mergeConfig.ts](https://github.com/zjx0905/axios-miniprogram/blob/main/src/core/mergeConfig.ts) 。 +具体配置合并策略请参阅 [mergeConfig.ts](https://github.com/zjx0905/axios-miniprogram/blob/main/src/core/mergeConfig.ts) 。 diff --git a/docs/pages/basics/download.md b/docs/pages/basics/download.md index 10ad9fd..b1686d4 100644 --- a/docs/pages/basics/download.md +++ b/docs/pages/basics/download.md @@ -5,7 +5,7 @@ title: 下载文件 # {{ $frontmatter.title }} ::: tip {{ $frontmatter.title }} -下载文件资源到本地,必须使用 `GET` 方法请求,并将请求配置的 `download` 属性设置为 `true`。 +下载文件资源到本地,必须使用 `GET` 方法请求,并将配置项 `download` 设置为 `true`。 ::: ## 普通的下载请求 @@ -36,7 +36,7 @@ axios ## 携带参数的下载请求 -也可以指定文件下载后存储的路径 (本地路径)。 +可以指定文件下载后存储的路径 (本地路径)。 ```ts import axios from 'axios-miniprogram'; @@ -64,7 +64,7 @@ axios ## 监听下载进度 -也可以监听下载进度变化。 +可以监听下载进度变化。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/dynamic-url.md b/docs/pages/basics/dynamic-url.md index 1f07f8f..0407a0f 100644 --- a/docs/pages/basics/dynamic-url.md +++ b/docs/pages/basics/dynamic-url.md @@ -5,15 +5,15 @@ title: 动态地址 # {{ $frontmatter.title }} ::: tip {{ $frontmatter.title }} -简化设置地址参数。 +简化地址参数的设置方式。 ::: -## 设置 `params` 动态参数 +## 设置请求参数 -可以设置属性 `params`,最终会从 `params` 中获取到对应的值。 +可以设置请求参数,最终会从请求参数中获取对应的值。 ::: warning 注意 -获取到值之后,会从 `params` 中删除对应的属性。 +获取到值后会从请求参数中删除对应的值。 ::: ```ts @@ -34,9 +34,9 @@ axios('https://api.com/:id', { }); ``` -## 设置 `data` 动态参数 +## 设置请求数据 -可以设置属性 `data`,最终会从 `data` 中获取到对应的值。 +可以设置请求数据,最终会从请求数据中获取对应的值。 ```ts import axios from 'axios-miniprogram'; @@ -57,9 +57,9 @@ axios('https://api.com/:id', { }); ``` -## 同时设置 `params` 和 `data` +## 同时设置请求参数和请求数据 -可以同时设置 `params` 和 `data`,会优先从 `params` 中获取对应的值。 +可以同时同时设置请求参数和请求数据,会优先从请求参数中获取对应的值。 ```ts import axios from 'axios-miniprogram'; @@ -81,14 +81,14 @@ axios('https://api.com/:id', { // 失败之后做些什么 }); -// 请求的服务端地址 https://api.com/1/2 -axios('https://api.com/:id1/:id2', { +// 请求的服务端地址 https://api.com/1/test +axios('https://api.com/:id/:name', { method: 'POST', params: { - id1: 1, + id: 1, }, data: { - id2: 2, + name: 'test', }, }) .then((response) => { diff --git a/docs/pages/basics/error-handler.md b/docs/pages/basics/error-handler.md index 2142b82..07e6cf3 100644 --- a/docs/pages/basics/error-handler.md +++ b/docs/pages/basics/error-handler.md @@ -8,17 +8,16 @@ title: 错误处理 当请求失败时,可以对错误进行处理。 ::: -## 使用 `validateStatus` 抛出错误 +## 校验状态抛出错误 -可以使用 `validateStatus` 自定义抛出错误的 HTTP code。 +可以设置校验状态,自定义抛出错误的状态码。 ```ts import axios from 'axios-miniprogram'; axios('https://api.com/test', { validateStatus(status) { - // status 小于 200 大于 299 会抛出错误 - return status >= 200 && status < 300; + return status === 200; }, }) .then((response) => { @@ -29,7 +28,7 @@ axios('https://api.com/test', { }); ``` -## 在 `catch` 中处理错误 +## 用 `catch` 处理错误 可以处理不同类型的错误。 @@ -71,7 +70,7 @@ axios('https://api.com/test') }); ``` -## 使用 `errorHandler` 处理错误 +## 用 `errorHandler` 处理错误 可以使用 `errorHandler` 处理不同类型的错误。 @@ -119,7 +118,7 @@ axios('https://api.com/test', { ## 全局错误处理 -可以把 `errorHandler` 设置到默认配置中,每一个请求都可以进行错误处理。 +可以设置全局错误处理,对每个请求生效。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/params-serializer.md b/docs/pages/basics/params-serializer.md index 85e6b17..233c38c 100644 --- a/docs/pages/basics/params-serializer.md +++ b/docs/pages/basics/params-serializer.md @@ -10,10 +10,11 @@ title: 参数系列化 ## 自定义参数系列化器 -可以用自己的方式对参数进行系列化。 +可以用自己的方式系列化参数。 ```ts import axios from 'axios-miniprogram'; +import qs from 'qs'; axios('https://api.com', { params: { diff --git a/docs/pages/basics/request.md b/docs/pages/basics/request.md index bd58fb5..05db1f8 100644 --- a/docs/pages/basics/request.md +++ b/docs/pages/basics/request.md @@ -27,7 +27,7 @@ axios ## 携带请求配置 -也可以传递第二个参数 `config`,用于指定请求方法以及其他配置项。 +可以额外传递第二个参数 `config`,用于指定请求方法以及其他配置项。 ```ts import axios from 'axios-miniprogram'; @@ -50,7 +50,7 @@ axios ## 仅有请求配置 -也可以忽略以上示例,直接传递 `config` 发送请求。 +可以直接传递 `config` 发送请求。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/response.md b/docs/pages/basics/response.md index a5a46f5..d27300b 100644 --- a/docs/pages/basics/response.md +++ b/docs/pages/basics/response.md @@ -44,7 +44,7 @@ axios('https//api.com') ## 平台属性 -请求成功返回的 `response` 可能还带有平台特有的属性,具体情况取决于平台特性。 +请求成功返回的 `response` 可能带有平台特有的属性,具体情况取决于平台特性。 微信小程序示例: diff --git a/docs/pages/basics/transform-data.md b/docs/pages/basics/transform-data.md index 9d96316..ee62645 100644 --- a/docs/pages/basics/transform-data.md +++ b/docs/pages/basics/transform-data.md @@ -5,7 +5,93 @@ title: 转换数据 # {{ $frontmatter.title }} ::: tip {{ $frontmatter.title }} -支持 请求发出前转换请求数据,响应到达 `then` 之前转换响应数据。 +请求发出前转换请求数据,响应到达 `then` 之前转换响应数据。 ::: -未完待续... +## 转换请求数据 + +可以转换请求数据,只对允许携带请求数据的请求方法生效,允许携带请求数据的方法有:`POST`、`PUT`、`PATCH`。 + +```ts +import axios from 'axios-miniprogram'; + +axios('test', { + method: 'POST', + transformRequest(data, headers) { + return JSON.stringify(data); + }, +}); +``` + +也支持多次转换。 + +```ts +import axios from 'axios-miniprogram'; + +axios('test', { + method: 'POST', + transformRequest: [ + (data, headers) => { + return JSON.stringify(data); + }, + (data, headers) => { + return encodeURIComponent(data); + }, + ], +}); +``` + +## 全局转换请求数据 + +可以设置全局转换请求数据,对每个请求生效。 + +```ts +import axios from 'axios-miniprogram'; + +axios.defaults.transformRequest = (data, headers) => { + return JSON.stringify(data); +}; +``` + +## 转换响应数据 + +可以转换响应数据。 + +```ts +import axios from 'axios-miniprogram'; + +axios('test', { + transformResponse(data, headers) { + return JSON.parse(data); + }, +}); +``` + +也支持多次转换。 + +```ts +import axios from 'axios-miniprogram'; + +axios('test', { + transformResponse: [ + (data, headers) => { + return decodeURIComponent(data); + }, + (data, headers) => { + return JSON.parse(data); + }, + ], +}); +``` + +## 全局转换响应数据 + +可以设置全局转换响应数据,对每个请求生效。 + +```ts +import axios from 'axios-miniprogram'; + +axios.defaults.transformResponse = (data, headers) => { + return JSON.parse(data); +}; +``` diff --git a/docs/pages/basics/upload.md b/docs/pages/basics/upload.md index 2da344e..5eb3925 100644 --- a/docs/pages/basics/upload.md +++ b/docs/pages/basics/upload.md @@ -5,7 +5,7 @@ title: 上传文件 # {{ $frontmatter.title }} ::: tip {{ $frontmatter.title }} -将本地资源上传到服务器,必须使用 `POST` 方法请求,并将请求配置的 `upload` 属性设置为 `true`。 +将本地资源上传到服务器,必须使用 `POST` 方法请求,并将请求配置项 `upload` 设置为 `true`。 ::: ## 普通的上传请求 diff --git a/src/axios.ts b/src/axios.ts index a5895a3..f34e08c 100644 --- a/src/axios.ts +++ b/src/axios.ts @@ -45,9 +45,9 @@ export interface AxiosStatic extends AxiosInstance { /** * 创建 axios 实例 * - * @param defaults 默认配置 + * @param config 默认配置 */ - create(defaults?: AxiosRequestConfig): AxiosInstance; + create(config?: AxiosRequestConfig): AxiosInstance; /** * 创建适配器 */ @@ -62,8 +62,8 @@ export interface AxiosStatic extends AxiosInstance { isAxiosError: typeof isAxiosError; } -function createInstance(defaults: AxiosRequestConfig) { - const context = new Axios(defaults); +function createInstance(config: AxiosRequestConfig) { + const context = new Axios(config); const instance = context.request as AxiosInstance; Object.assign(instance, context); @@ -74,8 +74,8 @@ function createInstance(defaults: AxiosRequestConfig) { const axios = createInstance(defaults) as AxiosStatic; -axios.create = function create(defaults) { - return createInstance(mergeConfig(axios.defaults, defaults)); +axios.create = function create(config) { + return createInstance(mergeConfig(axios.defaults, config)); }; axios.Axios = Axios; diff --git a/src/core/Axios.ts b/src/core/Axios.ts index 7f90882..cf3c2dc 100644 --- a/src/core/Axios.ts +++ b/src/core/Axios.ts @@ -171,13 +171,21 @@ export interface AxiosRequestConfig */ cancelToken?: CancelToken; /** - * 上传 + * 下载文件 + */ + download?: boolean; + /** + * 上传文件 */ upload?: boolean; /** - * 下载 + * 请求参数系列化函数 */ - download?: boolean; + paramsSerializer?: (params?: AnyObject) => string; + /** + * 校验状态码 + */ + validateStatus?: (status: number) => boolean; /** * 转换请求数据 */ @@ -198,14 +206,6 @@ export interface AxiosRequestConfig * 监听下载进度 */ onDownloadProgress?: AxiosProgressCallback; - /** - * 请求参数系列化函数 - */ - paramsSerializer?: (params?: AnyObject) => string; - /** - * 校验状态码 - */ - validateStatus?: (status: number) => boolean; } /** @@ -311,11 +311,11 @@ export default class Axios extends AxiosDomain { /** * 派生领域 */ - fork = (defaults: AxiosRequestConfig = {}) => { - if (isString(defaults.baseURL) && !isAbsoluteURL(defaults.baseURL)) { - defaults.baseURL = combineURL(this.defaults.baseURL, defaults.baseURL); + fork = (config: AxiosRequestConfig = {}) => { + if (isString(config.baseURL) && !isAbsoluteURL(config.baseURL)) { + config.baseURL = combineURL(this.defaults.baseURL, config.baseURL); } - return new AxiosDomain(mergeConfig(this.defaults, defaults), (config) => + return new AxiosDomain(mergeConfig(this.defaults, config), (config) => this.#processRequest(config), ); };