blackteay/fes.js
1
0
Fork 0
mirror of https://github.com/WeBankFinTech/fes.js.git synced 2025-04-05 03:05:07 +08:00
Code Issues Projects Releases Wiki Activity

docs: 优化文档构建

Browse Source
This commit is contained in:
winixt 2023-08-03 16:08:41 +08:00
parent 61fa8be45e
commit d668d06dc8
2 changed files with 248 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

218
docs/reference/plugin/plugins/request-4.md Normal file
View File

@ -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 特有的配置不在支持

90
docs/reference/plugin/plugins/request.md
View File

@ -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 特有的配置不在支持