From e2ca3fccc0175aedf7e7bed05ff8f5c7de8fca97 Mon Sep 17 00:00:00 2001 From: winixt Date: Thu, 3 Aug 2023 16:08:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BC=98=E5=8C=96=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=9E=84=E5=BB=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/plugin/plugins/request-4.md | 218 +++++++++++++++++++++ docs/reference/plugin/plugins/request.md | 90 +++------ 2 files changed, 248 insertions(+), 60 deletions(-) create mode 100644 docs/reference/plugin/plugins/request-4.md diff --git a/docs/reference/plugin/plugins/request-4.md b/docs/reference/plugin/plugins/request-4.md new file mode 100644 index 00000000..9d037401 --- /dev/null +++ b/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 特有的配置不在支持 diff --git a/docs/reference/plugin/plugins/request.md b/docs/reference/plugin/plugins/request.md index 9d037401..ff8333d5 100644 --- a/docs/reference/plugin/plugins/request.md +++ b/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 - 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) { + dataHandler(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。 - -### 请求 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(); -``` +若 `cache` 传 `true`，则默认使用 `ram` 缓存类型，缓存时间 3min。 ### 结合 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 特有的配置不在支持