fes.js/docs/reference/plugin/plugins/request.md

# @fesjs/plugin-request

基于 axios 封装的 request，内置防止重复请求、请求节流、错误处理等功能。

## 启用方式

在 `package.json` 中引入依赖：

```json
{
    "dependencies": {
        "@fesjs/fes": "^2.0.0",
        "@fesjs/plugin-request": "^2.0.0"
    }
}
```

## 配置

### 构建时配置

```js
export default {
    request: {
        dataField: 'result',
    },
};
```

#### dataField

-   类型： `string`
-   默认值： `''`
-   详情：

    `dataField` 对应接口中的数据字段。假设接口统一的规范是 `{ code: string, result: any}`，可配置 `dataField: 'result'`， 直接获取数据。如果个别接口不符合这个规范，可在第三个参数加上 `dataField: false`。

```js
// 构建时配置 dataField: 'result'

import { request } from '@fesjs/fes';

// 假设相应体为： {code: '0',  result: {say: 'hello'}}
const result = await request('/path/to/query/');

// {say: 'hello'}
console.log(result);

// 假设相应体为： {code: '0',  data: {say: 'hello'}}，其中 result 字段换成了 data
const response1 = await request('/special/to/query/', null, { dataField: false });

// {code: '0',  data: {say: 'hello'}}
console.log(response1);

// 或者：假设相应体为： {code: '0',  data: {say: 'hello'}}，其中 result 字段换成了 data
const response2 = await request('/special/to/query/', null, { dataField: 'data' });

// {say: 'hello'}
console.log(response2);
```

### 运行时配置

在 `app.js` 中进行运行时配置。

```js
export const request = {
    // 格式化 response.data (只有 response.data 类型为 object 才会调用)
    responseDataAdaptor: (data) => {
        data.code = data.code === '200' ? '0' : data.code;
        return data;
    },
    // 关闭 response data 校验（只判断 xhr status）
    closeResDataCheck: false,
    // 请求拦截器
    requestInterceptors: [],
    // 响应拦截器
    responseInterceptors: [],
    // 错误处理
    // 内部以 reponse.data.code === '0' 判断请求是否成功
    // 若使用其他字段判断，可以使用 responseDataAdaptor 对响应数据进行格式
    errorHandler: {
        11199(response) {
            // 特殊 code 处理逻辑
        },
        404(error) {},
        default(error) {
            // 异常统一处理
        },
    },
    // 其他 axios 配置
    ...otherConfigs,
};
```

#### skipErrorHandler

-   类型： `boolean | string | number | array<string | number>`
-   默认值： ``
-   详情：

    指定当前请求的某些错误状态不走 `errorHandler`，单独进行处理。如果设置为 `true`，当前请求的错误处理都不走 `errorHandler`。

-   示列：

```js
import { request } from '@fesjs/fes';

request('/api/login', null, {
    skipErrorHandler: '110',
})
    .then((res) => {
        // do something
    })
    .catch((err) => {
        // 这里处理 code 为 110 的异常
        // 此时 errorHandler[110] 函数不会生效，也不会执行 errorHandler.default
    });
```

## 使用

### 发起一个普通 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',
    },
    {
        cache: {
            cacheType: 'ram', // ram: 内存，session: sessionStorage，local：localStorage
            cacheTime: 1000 * 60 * 3, // 缓存时间：默认3min
        },
    },
)
    .then((res) => {
        // do something
    })
    .catch((err) => {
        // 处理异常
    });
```

若 `cache` 传 `true`，则默认使用 `ram` 缓存类型，缓存时间 3min。

### 结合 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,
        };
    },
};
```

## API

### request

-   **类型**：函数

-   **详情**：请求后端接口
-   **参数**：
    -   url: 后端接口 url
    -   data: 参数
    -   options:  配置（ 支持 axios 所有配置）
-   **返回值**: Promise

### useRequest

request 的封装，返回响应式 `loading`、`error`、 `data`