docs: 介绍拦截器

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' },

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);
+```

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);
+```

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';

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) => {
     // 成功之后做些什么

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) 。

docs/pages/basics/error-handler.md

@@ -71,7 +71,7 @@ axios('https://api.com/test')
   });
 ```
 
-## 使用 `errorHandler` 处理错误。
+## 使用 `errorHandler` 处理错误
 
 可以使用 `errorHandler` 处理不同类型的错误。
 

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;