diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 09e1855..4096d2e 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -112,6 +112,7 @@ function sidebar() { text: '基础', items: [ { text: '请求配置', link: '/basics/config' }, + { text: '默认配置', link: '/basics/defaults' }, { text: '响应体', link: '/basics/response' }, { text: '发送请求', link: '/basics/request' }, { text: '上传文件', link: '/basics/upload' }, diff --git a/docs/pages/advanced/request-interceptor.md b/docs/pages/advanced/request-interceptor.md index f60c95b..28abf8c 100644 --- a/docs/pages/advanced/request-interceptor.md +++ b/docs/pages/advanced/request-interceptor.md @@ -4,4 +4,79 @@ title: 请求拦截器 # {{ $frontmatter.title }} -待续... +::: tip {{ $frontmatter.title }} +用于请求发出前拦截请求。 + +通常会用于转换请求配置，或实现一些自定义功能。 +::: + +## 添加请求拦截器 + +可以添加请求拦截器。 + +```ts +import axios from 'axios-miniprogram'; + +axios.interceptors.request.use( + function (config) { + // 在发送请求之前做些什么 + return config; + }, + function (error) { + // 对请求错误做些什么 + return Promise.reject(error); + }, +); +``` + +也可以添加多个请求拦截器，后添加的会先执行。 + +```ts +import axios from 'axios-miniprogram'; + +// 先添加 后执行 +axios.interceptors.request.use( + function (config) { + // 在发送请求之前做些什么 + return config; + }, + function (error) { + // 对请求错误做些什么 + return Promise.reject(error); + }, +); + +// 后添加 先执行 +axios.interceptors.request.use( + function (config) { + // 在发送请求之前做些什么 + return config; + }, + function (error) { + // 对请求错误做些什么 + return Promise.reject(error); + }, +); +``` + +## 移除请求拦截器 + +可以移除不再需要的请求拦截器。 + +```ts +import axios from 'axios-miniprogram'; + +const ejectId = axios.interceptors.request.use( + function (config) { + // 在发送请求之前做些什么 + return config; + }, + function (error) { + // 对请求错误做些什么 + return Promise.reject(error); + }, +); + +// 移除请求拦截器 +axios.interceptors.request.eject(ejectId); +``` diff --git a/docs/pages/advanced/response-interceptor.md b/docs/pages/advanced/response-interceptor.md index 68c4047..3a05f5d 100644 --- a/docs/pages/advanced/response-interceptor.md +++ b/docs/pages/advanced/response-interceptor.md @@ -4,4 +4,79 @@ title: 响应拦截器 # {{ $frontmatter.title }} -待续... +::: tip {{ $frontmatter.title }} +用于 `response` 到达 `then` 之前，或 `error` 到达 `catch` 之前拦截响应。 + +通常会用于处理错误，但对于处理错误而言，使用 `errorhandler` 会是更好的选择。 +::: + +## 添加响应拦截器 + +可以添加响应拦截器。 + +```ts +import axios from 'axios-miniprogram'; + +axios.interceptors.response.use( + function (response) { + // 在 then 之前做些什么 + return response; + }, + function (error) { + // 在 catch 之前做些什么 + return Promise.reject(error); + }, +); +``` + +也可以添加多个响应拦截器，先添加的会先执行。 + +```ts +import axios from 'axios-miniprogram'; + +// 先添加 先执行 +axios.interceptors.response.use( + function (response) { + // 在 then 之前做些什么 + return response; + }, + function (error) { + // 在 catch 之前做些什么 + return Promise.reject(error); + }, +); + +// 后添加 后执行 +axios.interceptors.response.use( + function (response) { + // 在 then 之前做些什么 + return response; + }, + function (error) { + // 在 catch 之前做些什么 + return Promise.reject(error); + }, +); +``` + +## 移除响应拦截器 + +可以移除不再需要的响应拦截器。 + +```ts +import axios from 'axios-miniprogram'; + +const ejectId = axios.interceptors.response.use( + function (response) { + // 在 then 之前做些什么 + return response; + }, + function (error) { + // 在 catch 之前做些什么 + return Promise.reject(error); + }, +); + +// 移除响应拦截器 +axios.interceptors.response.eject(ejectId); +``` diff --git a/docs/pages/basics/cancel.md b/docs/pages/basics/cancel.md index 1fdf5d2..bedd87a 100644 --- a/docs/pages/basics/cancel.md +++ b/docs/pages/basics/cancel.md @@ -55,9 +55,9 @@ axios('https://api.com/test', { cancel('request canceled'); ``` -## 判断异常是否来自取消请求 +## 判断取消请求 -也可以用 `axios.isCancel` 判断异常是否来自取消请求，从而做出相应的处理。 +也可以用 `axios.isCancel` 判断请求错误是否来自取消请求，从而做出相应的处理。 ```ts import axios from 'axios-miniprogram'; diff --git a/docs/pages/basics/config.md b/docs/pages/basics/config.md index 19c354d..d431f34 100644 --- a/docs/pages/basics/config.md +++ b/docs/pages/basics/config.md @@ -146,19 +146,49 @@ axios({ ## 自定义属性 -也可以设置自定义属性。 +也可以设置自定义属性，从而实现一些自定义功能。 自定义属性可以根据需要随意设置。 ```ts import axios from 'axios-miniprogram'; -axios({ - // 这是一个自定义配置 - user: '123', +// 错误处理 +axios.defaults.errorHandler = (error) => { + if (axios.isAxiosError(error)) { + // 显示错误信息 + if (error.config.showError) { + wx.showToast({ + title: error.response.data.errMsg, + }); + } + } +}; - // 这也是一个自定义配置 +// 请求拦截器 +axios.interceptors.request.use((config) => { + // 自动显示 loading + if (config.showLoading) { + wx.showLoading(); + } + return config; +}); + +// 响应拦截器 +axios.interceptors.response.use((response) => { + // 自动隐藏 loading + if (response.config.showLoading) { + wx.hideLoading(); + } + return response; +}); + +axios({ + // 请求时自动 loading showLoading: true, + + // 出错时显示错误信息 + showError: true, }) .then((response) => { // 成功之后做些什么 diff --git a/docs/pages/basics/defaults.md b/docs/pages/basics/defaults.md new file mode 100644 index 0000000..357b48f --- /dev/null +++ b/docs/pages/basics/defaults.md @@ -0,0 +1,172 @@ +--- +title: 默认配置 +--- + +# {{ $frontmatter.title }} + +::: tip {{ $frontmatter.title }} +默认配置 `defaults` 会作用于每个请求。 +::: + +## 默认值 + +在不更改默认配置 `defaults` 的情况下，它依然会存在一些默认值，在 [defaults.ts](https://github.com/zjx0905/axios-miniprogram/blob/main/src/defaults.ts) 中定义，大概长下面这样。 + +```ts +{ + // 适配器，在支持的平台中有值。 + // 对于不支持平台而言，此值始终为 undefined，需要您手动适配。 + adapter: getAdapterDefault(), + + // 请求头 + headers: { + // 通用请求头 + common: { + Accept: 'application/json, text/plain, */*', + }, + options: {}, // OPTIONS 方法请求头 + get: {}, // GET 方法请求头 + head: {}, // HEAD 方法请求头 + post: {}, // POST 方法请求头 + put: {}, // PUT 方法请求头 + patch: {}, // PATCH 方法请求头 + delete: {}, // DELETE 方法请求头 + trace: {}, // TRACE 方法请求头 + connect: {}, // CONNECT 方法请求头 + }, + + // 校验状态码 + validateStatus(status: number): boolean { + return status >= 200 && status < 300; + }, + + // 返回的数据格式 + dataType: 'json', + + // 响应的数据类型 + responseType: 'text', + + // 超时时长 + timeout: 10000, +} +``` + +## 设置属性 + +可以给属性设置默认值。 + +部分示例： + +```ts +import axios from 'axios-miniprogram'; + +// 基础服务器地址 +axios.defaults.baseURL = 'https://api.com'; + +// 通用请求头 +axios.defaults.headers.common['Content-Type'] = 'application/json'; + +// POST 方法请求头 +axios.defaults.headers.post['Content-Type'] = + 'applicatioapplication/x-www-form-urlencoded'; + +// 超时时间 +axios.defaults.timeout = '60000'; + +// 校验状态码 +axios.defaults.validateStatus = (status) => { + return status === 200; +}; + +// 错误处理 +axios.defaults.errorHandler = (error) => { + console.log('出错了'); +}; + +// 监听上传进度 +axios.defaults.onUploadProgress = (event) => { + console.log('上传中：' + event.progress); +}; +``` + +## 设置平台属性 + +也可以给平台特有属性设置默认值，具体情况取决于平台特性。 + +微信小程序示例： + +```ts +import axios from 'axios-miniprogram'; + +// 开启 http2 +axios.defaults.enableHttp2 = true; + +// 开启 quic +axios.defaults.enableQuic = true; + +// 开启 cache +axios.defaults.enableCache = true; + +// 开启 HttpDNS 服务。 +axios.defaults.enableHttpDNS = true; + +// HttpDNS 服务商 Id。 +axios.defaults.httpDNSServiceId = '123'; + +// wifi 下使用移动网络发送请求 +axios.defaults.forceCellularNetwork = false; +``` + +想要了解更多请自行参阅对应平台文档。 + +## 设置自定义属性 + +也可以给自定义属性设置默认值，实现一些自定义功能。 + +```ts +import axios from 'axios-miniprogram'; + +// 出错时显示错误信息 +axios.defaults.showError = true; + +// 错误处理 +axios.defaults.errorHandler = (error) => { + if (axios.isAxiosError(error)) { + // 显示错误信息 + if (error.config.showError) { + wx.showToast({ + title: error.response.data.errMsg, + }); + } + } +}; + +// 请求时自动 loading +axios.defaults.showLoading = true; + +// 请求拦截器 +axios.interceptors.request.use((config) => { + // 自动显示 loading + if (config.showLoading) { + wx.showLoading(); + } + return config; +}); + +// 响应拦截器 +axios.interceptors.response.use((response) => { + // 自动隐藏 loading + if (response.config.showLoading) { + wx.hideLoading(); + } + return response; +}); +``` + +## 合并策略 + +在发送请求时，默认配置 `defaults` 和请求配置配 `config` 将会按优先级进行合并。 + +其中 `url/method/data/upload/download` 只从 `config` 取值，`headers/params` 进行深度合并，其余属性则会优先从 `config` 取值。 + +具体合并策略请参阅 [mergeConfig.ts](https://github.com/zjx0905/axios-miniprogram/blob/main/src/core/mergeConfig.ts) 。 diff --git a/docs/pages/basics/error-handler.md b/docs/pages/basics/error-handler.md index 258484d..83ff417 100644 --- a/docs/pages/basics/error-handler.md +++ b/docs/pages/basics/error-handler.md @@ -71,7 +71,7 @@ axios('https://api.com/test') }); ``` -## 使用 `errorHandler` 处理错误。 +## 使用 `errorHandler` 处理错误 可以使用 `errorHandler` 处理不同类型的错误。 diff --git a/src/defaults.ts b/src/defaults.ts index 3e91d9c..342c0ae 100644 --- a/src/defaults.ts +++ b/src/defaults.ts @@ -2,27 +2,40 @@ import { getAdapterDefault } from './adapter'; import { AxiosInstanceDefaults } from './axios'; const defaults: AxiosInstanceDefaults = { + // 适配器，在支持的平台中有值。 + // 对于不支持平台而言，此值始终为 undefined，需要您手动适配。 adapter: getAdapterDefault(), + + // 请求头 headers: { + // 通用请求头 common: { Accept: 'application/json, text/plain, */*', }, - options: {}, - get: {}, - head: {}, - post: {}, - put: {}, - patch: {}, - delete: {}, - trace: {}, - connect: {}, + options: {}, // OPTIONS 方法请求头 + get: {}, // GET 方法请求头 + head: {}, // HEAD 方法请求头 + post: {}, // POST 方法请求头 + put: {}, // PUT 方法请求头 + patch: {}, // PATCH 方法请求头 + delete: {}, // DELETE 方法请求头 + trace: {}, // TRACE 方法请求头 + connect: {}, // CONNECT 方法请求头 }, + + // 校验状态码 validateStatus(status: number): boolean { return status >= 200 && status < 300; }, - timeout: 10000, + + // 返回的数据格式 dataType: 'json', + + // 响应的数据类型 responseType: 'text', + + // 超时时长 + timeout: 10000, }; export default defaults;