docs: 优化文档构建

docs/reference/plugin/plugins/request-4.md

@@ -0,0 +1,218 @@
+# @fesjs/plugin-request
+
+基于 fetch 封装的 request，内置防止重复请求、请求缓存、错误处理等功能。
+
+## 启用方式
+
+在 `package.json` 中引入依赖：
+
+```json
+{
+    "dependencies": {
+        "@fesjs/fes": "^3.0.0",
+        "@fesjs/plugin-request": "^4.0.0-beta.0"
+    }
+}
+```
+
+## 运行时配置
+
+入口文件的全局配置，具体请求的配置参数会覆盖全局配置，支持 [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#sending_a_request_with_credentials_included) 所有的参数。
+
+```js
+import { defineRuntimeConfig } from '@fesjs/fes';
+
+export default defineRuntimeConfig({
+    request: {
+        baseURL: '',
+        timeout: 10000, // 默认 10s
+        method: 'POST', // 默认 post
+        mergeRequest: false, // 是否合并请求
+        responseType: null, // 可选 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData'，默认根据 content-type 处理
+        credentials: 'include', // 默认 include, 'include' | 'same-origin' | 'omit'
+        headers: {}, // 传给服务器的 header
+        cacheData: false, // 是否缓存
+        requestInterceptor: (config: Config) => Config,
+        responseInterceptor: (response: RequestResponse) => RequestResponse,
+        transformData(data, response) {
+            // 处理响应内容异常
+            if (isPlainObject(data)) {
+                if (data.code === '10000') {
+                    return Promise.reject(data);
+                }
+                return data?.result ? data.result : data;
+            }
+            return data;
+        },
+        // http 异常，和插件异常
+        errorHandler(error) {
+            if (error.response) {
+                // 请求成功发出且服务器也响应了状态码，但状态代码超出了 2xx 的范围
+                console.log(error.response.data);
+                console.log(error.response.status);
+                console.log(error.response.headers);
+            } else if (error.msg) {
+                console.log(error.msg);
+            } else {
+                // 发送请求时出了点问题
+                console.log('Error', error.message);
+            }
+            console.log(error.config);
+        },
+        // 支持其他 fetch 配置
+        ...otherConfigs,
+    },
+});
+```
+
+## API
+
+### request
+
+-   **类型**：函数
+
+-   **详情**：请求后端接口
+-   **参数**：
+
+    -   url: 后端接口 url
+    -   data: 参数
+    -   options: 配置支持 [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#sending_a_request_with_credentials_included) 所有的参数，和插件扩展参数。
+
+-   **返回值**: Promise
+
+### useRequest
+
+request 的封装，返回响应式 `loading`、`error`、 `data`
+
+## 使用
+
+### 发起一个普通 post 请求
+
+```js
+import { request } from '@fesjs/fes';
+
+request('/api/login', {
+    username: 'robby',
+    password: '123456',
+})
+    .then((res) => {
+        // do something
+    })
+    .catch((err) => {
+        // 处理异常
+    });
+```
+
+### merge 重复请求
+
+连续发送多个请求，会被合并成一个请求，不会报 `REPEAT` 接口错误。
+
+当发生 `REPEAT` 请求异常，并且确保自身代码合理的情况下，可以使用该配置。
+
+```js
+import { request } from '@fesjs/fes';
+
+request(
+    '/api/login',
+    {
+        username: 'robby',
+        password: '123456',
+    },
+    {
+        mergeRequest: true, // 在一个请求没有回来前，重复发送的请求会合并成一个请求
+    },
+)
+    .then((res) => {
+        // do something
+    })
+    .catch((err) => {
+        // 处理异常
+    });
+```
+
+### 请求缓存
+
+```js
+import { request } from '@fesjs/fes';
+
+request(
+    '/api/login',
+    {
+        username: 'robby',
+        password: '123456',
+    },
+    {
+        cacheData: {
+            cacheType: 'ram', // ram: 内存，session: sessionStorage，local：localStorage
+            cacheTime: 1000 * 60 * 3, // 缓存时间：默认3min
+        },
+    },
+)
+    .then((res) => {
+        // do something
+    })
+    .catch((err) => {
+        // 处理异常
+    });
+```
+
+若 `cacheData` 传 `true`，则默认使用 `ram` 缓存类型，缓存时间 3min。
+
+### 请求 abort
+
+```javascript
+import { request } from '@fesjs/fes';
+
+const controller = new AbortController();
+request('/url/abort', null, {
+    signal: controller.signal,
+}).then((response) => {
+    console.log('process response: ' + response);
+});
+// cancel the request
+controller.abort();
+```
+
+### 获取 response headers
+
+```javascript
+import { rawRequest } from '@fesjs/fes';
+
+const controller = new AbortController();
+rawRequest('/url/abort', null, {
+    signal: controller.signal,
+}).then((response) => {
+    console.log('process headers: ' + response.headers);
+});
+// cancel the request
+controller.abort();
+```
+
+### 结合 use 使用
+
+```js
+import { useRequest } from '@fesjs/fes';
+
+export default {
+    setup() {
+        const { loading, data, error } = useRequest('/api/login', {
+            username: 'robby',
+            password: '123456',
+        });
+
+        return {
+            loading,
+            data,
+            error,
+        };
+    },
+};
+```
+
+## 3.x 升级到 4.x
+
+1. 缓存参数 cache 改成 cacheData（避免与 fetch 原本的 cache 冲突）
+2. dataHandler 改成 transformData
+3. requestInterceptors 改为 requestInterceptor，不在支持数组，只支持函数
+4. responseInterceptors 改为 responseInterceptor，不在支持数组，只支持函数
+5. 其他 axios 特有的配置不在支持

docs/reference/plugin/plugins/request.md

@@ -1,6 +1,8 @@
 # @fesjs/plugin-request
 
-基于 fetch 封装的 request，内置防止重复请求、请求缓存、错误处理等功能。
+基于 axios 封装的 request，内置防止重复请求、请求缓存、错误处理等功能。
+
+[4.x 版本请点击](./request-4.md)
 
 ## 启用方式
 
@@ -10,39 +12,35 @@
 {
     "dependencies": {
         "@fesjs/fes": "^3.0.0",
-        "@fesjs/plugin-request": "^4.0.0-beta.0"
+        "@fesjs/plugin-request": "^3.0.0"
     }
 }
 ```
 
 ## 运行时配置
 
-入口文件的全局配置，具体请求的配置参数会覆盖全局配置，支持 [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#sending_a_request_with_credentials_included) 所有的参数。
+入口文件的全局配置，具体请求的配置参数会覆盖全局配置，支持 [axios](https://axios-http.com/zh/docs/req_config) 所有的参数。
 
 ```js
 import { defineRuntimeConfig } from '@fesjs/fes';
 
 export default defineRuntimeConfig({
     request: {
+        // API  前缀
         baseURL: '',
-        timeout: 10000, // 默认 10s
+        dataHandler(data, response) {
-        method: 'POST', // 默认 post
-        mergeRequest: false, // 是否合并请求
-        responseType: null, // 可选 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData'，默认根据 content-type 处理
-        credentials: 'include', // 默认 include, 'include' | 'same-origin' | 'omit'
-        headers: {}, // 传给服务器的 header
-        cacheData: false, // 是否缓存
-        requestInterceptor: (config: Config) => Config,
-        responseInterceptor: (response: RequestResponse) => RequestResponse,
-        transformData(data, response) {
             // 处理响应内容异常
-            if (isPlainObject(data)) {
+            if (data.code !== '0') {
                 if (data.code === '10000') {
-                    return Promise.reject(data);
+                    FMesseage.error('hello world');
                 }
-                return data?.result ? data.result : data;
+                if (data.code === '20000') {
+                    FMesseage.error('hello world');
+                }
+                throw new Error(response);
             }
-            return data;
+            // 响应数据格式化
+            return data?.result ? data.result : data;
         },
         // http 异常，和插件异常
         errorHandler(error) {
@@ -51,7 +49,13 @@ export default defineRuntimeConfig({
                 console.log(error.response.data);
                 console.log(error.response.status);
                 console.log(error.response.headers);
-            } else if (error.msg) {
+            } else if (error.request) {
+                // 请求已经成功发起，但没有收到响应
+                // `error.request` 在浏览器中是 XMLHttpRequest 的实例，
+                // 而在node.js中是 http.ClientRequest 的实例
+                console.log(error.request);
+            } else if (error.type) {
+                // 插件异常
                 console.log(error.msg);
             } else {
                 // 发送请求时出了点问题
@@ -59,7 +63,11 @@ export default defineRuntimeConfig({
             }
             console.log(error.config);
         },
-        // 支持其他 fetch 配置
+        // 请求拦截器
+        requestInterceptors: [],
+        // 响应拦截器
+        responseInterceptors: [],
+        // 支持其他 axios 配置
         ...otherConfigs,
     },
 });
@@ -76,7 +84,7 @@ export default defineRuntimeConfig({
 
     -   url: 后端接口 url
     -   data: 参数
-    -   options: 配置支持 [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#sending_a_request_with_credentials_included) 所有的参数，和插件扩展参数。
+    -   options: 配置支持 [axios](https://axios-http.com/zh/docs/req_config) 所有的参数，和插件扩展参数。
 
 -   **返回值**: Promise
 
@@ -142,7 +150,7 @@ request(
         password: '123456',
     },
     {
-        cacheData: {
+        cache: {
             cacheType: 'ram', // ram: 内存，session: sessionStorage，local：localStorage
             cacheTime: 1000 * 60 * 3, // 缓存时间：默认3min
         },
@@ -156,37 +164,7 @@ request(
     });
 ```
 
-若 `cacheData` 传 `true`，则默认使用 `ram` 缓存类型，缓存时间 3min。
+若 `cache` 传 `true`，则默认使用 `ram` 缓存类型，缓存时间 3min。
-
-### 请求 abort
-
-```javascript
-import { request } from '@fesjs/fes';
-
-const controller = new AbortController();
-request('/url/abort', null, {
-    signal: controller.signal,
-}).then((response) => {
-    console.log('process response: ' + response);
-});
-// cancel the request
-controller.abort();
-```
-
-### 获取 response headers
-
-```javascript
-import { rawRequest } from '@fesjs/fes';
-
-const controller = new AbortController();
-rawRequest('/url/abort', null, {
-    signal: controller.signal,
-}).then((response) => {
-    console.log('process headers: ' + response.headers);
-});
-// cancel the request
-controller.abort();
-```
 
 ### 结合 use 使用
 
@@ -208,11 +186,3 @@ export default {
     },
 };
 ```
-
-## 3.x 升级到 4.x
-
-1. 缓存参数 cache 改成 cacheData（避免与 fetch 原本的 cache 冲突）
-2. dataHandler 改成 transformData
-3. requestInterceptors 改为 requestInterceptor，不在支持数组，只支持函数
-4. responseInterceptors 改为 responseInterceptor，不在支持数组，只支持函数
-5. 其他 axios 特有的配置不在支持