ice/website/docs/guide/advanced/request.md

# 网络请求

:::tip
小程序端不支持该能力。
:::

大部分前端应用都会选择通过 HTTP(s) 协议与后端服务通讯。  
ice.js 提供了一套从 UI 交互到请求服务端数据的完整方案，通过切面编程的方式统一了数据请求管理，简化了设置参数、错误处理等逻辑的实现。

## 安装 [request 插件](https://www.npmjs.com/@ice/plugin-request)

网络请求是可选能力，在使用前需要单独安装 `@ice/plugin-request` 插件。

```bash
npm i @ice/plugin-request -D
```

在配置文件中添加插件：

```tsx title="ice.config.mts"
import { defineConfig } from '@ice/app';
import request from '@ice/plugin-request';

export default defineConfig(() => ({
  plugins: [
    request(),
  ],
}));
```

## 目录约定

框架约定 `service` 目录用于收敛请求逻辑，目录组织如下：

```diff
 src
 ├── models
+├── services                       // 定义全局数据请求，非必须
+│   └── user.ts
 └── pages
 |   ├── home
 |   │   ├── models
+|   │   ├── services               // 定义页面级数据请求
+|   │   |    └── repo.ts
 |   │   └── components
 |   ├── about
 |   │   ├── services
 |   │   ├── components
 |   │   └── index.tsx
 └── app.ts
```

通过调用 `request` 定义数据请求如下：

```ts title="pages/home/service/repo.ts"
import { request } from 'ice';

export default {
  // 简单场景
  async getUser() {
    return await request('/api/user');
  },

  // 参数场景
  async getRepo(id) {
    return await request(`/api/repo/${id}`);
  },

  // 格式化返回值
  async getDetail(params) {
    const data = await request({
      url: `/api/detail`,
      params
    });

    return data.map(item => {
      return {
        ...item,
        price: item.oldPrice,
        text: item.status === '1' ? '确定' : '取消'
      };
    });
  }
}
```

## 消费 service

消费 service 主要有两种方式：

- 在模型中调用 service：`service` -> `model` -> `view`
- 在视图中调用 service：`service` -> `view`

### 在模型中调用 service

> 结合 [状态管理](./store.md) 使用

- `service`：约定数据请求统一管理在 services 目录下；
- `model`：约定数据请求统一在 models 里进行调用；
- `view`：最终在视图里通过调用 models 的 effects 的方法触发数据请求。

在模型中调用定义好的 service：

```ts
import userService from '@/services/user';

// src/models/user.ts
export default {
  state: {
    name: 'taoxiaobao',
    age: 20,
  },
  reducers: {
    update(prevState, payload) {
      return { ...prevState, ...payload };
    },
  },
  effects: (dispatch) => ({
    async fetchUserInfo() {
      const data = await userService.getUser();
      dispatch.user.update(data);
    },
  }),
};
```

- 在视图中调用模型方法：

```tsx
import React, { useEffect } from 'react';
import store from '@/store';

const HomePage = () => {
  // 调用定义的 user 模型
  const [userState, userDispatchers] = store.useModel('user');

  useEffect(() => {
    // 调用 user 模型中的 fetchUserInfo 方法
    userDispatchers.fetchUserInfo();
  }, []);

  return <>Home</>;
};
```

### 在视图中调用 service

- `service`：约定数据请求统一管理在 services 目录下；
- `view`：最终在视图里通过 useRequest 直接调用 service 触发数据请求。

```tsx
import React, { useEffect } from 'react';
import { useRequest } from 'ice';
import userService from '@/services/user';

export default function HomePage() {
  // 调用 service
  const { data, error, loading, request } = useRequest(userService.getUser);

  useEffect(() => {
    // 触发数据请求
    request();
  }, []);

  return <>Home</>;
}
```

## API

### request

request 基于 axios 进行封装，在使用上整体与 axios 保持一致，差异点：

1. 默认只返回服务端响应的数据 `Response.data`，而不是整个 Response，如需返回整个 Response 请通过 `withFullResponse` 参数开启
2. 在 axios 基础上默认支持了多请求实例的能力

使用方式如下：

```ts
import { request } from 'ice';

async function getList() {
  const resData = await request({
    url: '/api/user',
  });
  console.log(resData.list);

  const { status, statusText, data } = await request({
    url: '/api/user',
    withFullResponse: true
  });
  console.log(data.list);
}
```

常用使用方式：

```js
request(RequestConfig);

request.get('/user', RequestConfig);
request.post('/user', data, RequestConfig);
```

RequestConfig:

```js
{
  // `url` is the server URL that will be used for the request
  url: '/user',
  // `method` is the request method to be used when making the request
  method: 'get', // default
  // `headers` are custom headers to be sent
  headers: {'X-Requested-With': 'XMLHttpRequest'},
  // `params` are the URL parameters to be sent with the request
  // Must be a plain object or a URLSearchParams object
  params: {
    ID: 12345
  },
  // `data` is the data to be sent as the request body
  // Only applicable for request methods 'PUT', 'POST', and 'PATCH'
  data: {
    firstName: 'Fred'
  },
  // `timeout` specifies the number of milliseconds before the request times out.
  // If the request takes longer than `timeout`, the request will be aborted.
  timeout: 1000, // default is `0` (no timeout)
  // `withCredentials` indicates whether or not cross-site Access-Control requests
  // should be made using credentials
  withCredentials: false, // default
  // `responseType` indicates the type of data that the server will respond with
  // options are: 'arraybuffer', 'document', 'json', 'text', 'stream'
  responseType: 'json', // default
  // should be made return full response
  withFullResponse: false,
  // request instance name
  instanceName: 'request2'
}
```

更完整的配置请 [参考](https://github.com/axios/axios#request-config)。

返回完整 Response Scheme 如下：

```ts
{
  // `data` is the response that was provided by the server
  data: {},

  // `status` is the HTTP status code from the server response
  status: 200,

  // `statusText` is the HTTP status message from the server response
  statusText: 'OK',

  // `headers` the HTTP headers that the server responded with
  // All header names are lower cased and can be accessed using the bracket notation.
  // Example: `response.headers['content-type']`
  headers: {},

  // `config` is the config that was provided to `axios` for the request
  config: {},

  // `request` is the request that generated this response
  // It is the last ClientRequest instance in node.js (in redirects)
  // and an XMLHttpRequest instance in the browser
  request: {}
}
```

### useRequest

使用 useRequest 可以极大的简化对请求状态的管理，useRequest 基于 [ahooks/useRequest](https://ahooks.js.org/zh-CN/hooks/use-request/index) 封装，差异点：

- 将 `requestMethod` 参数默认设置为上述的 `request`（即 axios），保证框架使用的一致性
- manual 参数默认值从 `false` 改为 `true`，因为实际业务更多都是要手动触发的
- 返回值 `run` 改为 `request`，因为更符合语义

#### API

```ts
const {
  // 请求返回的数据，默认为 undefined
  data,
  // 请求抛出的异常，默认为 undefined
  error,
  // 请求状态
  loading,
  // 手动触发请求，参数会传递给 service
  request,
  // 当次执行请求的参数数组
  params,
  // 取消当前请求，如果有轮询，停止
  cancel,
  // 使用上一次的 params，重新执行请求
  refresh,
  // 直接修改 data
  mutate,
  // 默认情况下，新请求会覆盖旧请求。如果设置了 fetchKey，则可以实现多个请求并行，fetches 存储了多个请求的状态
  fetches
} = useRequest(service, {
  // 默认为 true 即需要手动执行请求
  manual,
   // 初始化的 data
  initialData,
  // 请求成功时触发，参数为 data 和 params
  onSuccess,
  // 请求报错时触发，参数为 error 和 params
  onError,
  // 格式化请求结果
  formatResult,
  // 请求唯一标识
  cacheKey,
  // 设置显示 loading 的延迟时间，避免闪烁
  loadingDelay,
  // 默认参数
  defaultParams,
  // 轮询间隔，单位为毫秒
  pollingInterval,
  // 在页面隐藏时，是否继续轮询，默认为 true，即不会停止轮询
  pollingWhenHidden,
  // 根据 params，获取当前请求的 key
  fetchKey,
  // 在屏幕重新获取焦点或重新显示时，是否重新发起请求。默认为 false，即不会重新发起请求
  refreshOnWindowFocus,
  // 屏幕重新聚焦，如果每次都重新发起请求，不是很好，我们需要有一个时间间隔，在当前时间间隔内，不会重新发起请求，需要配置 refreshOnWindowFocus 使用
  focusTimespan,
  // 防抖间隔, 单位为毫秒，设置后，请求进入防抖模式
  debounceInterval,
  // 节流间隔, 单位为毫秒，设置后，请求进入节流模式。
  throttleInterval,
  // 只有当 ready 为 true 时，才会发起请求
  ready,
  // 在 manual = false 时，refreshDeps 变化，会触发请求重新执行
  refreshDeps,
});
```

#### 常用使用方式

```ts
import { useRequest } from 'ice';
// 用法 1：传入字符串
const { data, error, loading } = useRequest('/api/repo');

// 用法 2：传入配置对象
const { data, error, loading } = useRequest({
  url: '/api/repo',
  method: 'get',
});

// 用法 3：传入 service 函数
const { data, error, loading, request } = useRequest((id) => ({
  url: '/api/repo',
  method: 'get',
  data: { id },
});
```

更多使用方式详见 [ahooks/useRequest](https://ahooks.js.org/zh-CN/hooks/use-request/index)

### 请求配置

在实际项目中通常需要对请求进行全局统一的封装，例如配置请求的 baseURL、统一 header、拦截请求和响应等等，这时只需要在应用的的 appConfig 中进行配置即可。

```ts title="src/app.tsx"
import { defineRequestConfig } from '@ice/plugin-request/types';

export const requestConfig = defineRequestConfig({
  // 可选的，全局设置 request 是否返回 response 对象，默认为 false
  withFullResponse: false,

  baseURL: '/api',
  headers: {},
  // ...RequestConfig 其他参数

  // 拦截器
  interceptors: {
    request: {
      onConfig: (config) => {
        // 发送请求前：可以对 RequestConfig 做一些统一处理
        config.headers = { a: 1 };
        return config;
      },
      onError: (error) => {
        return Promise.reject(error);
      },
    },
    response: {
      onConfig: (response) => {
        // 请求成功：可以做全局的 toast 展示，或者对 response 做一些格式化
        if (!response.data.status !== 1) {
          alert('请求失败');
        }
        return response;
      },
      onError: (error) => {
        // 请求出错：服务端返回错误状态码
        console.log(error.response.data);
        console.log(error.response.status);
        console.log(error.response.headers);
        return Promise.reject(error);
      },
    },
  },
});
```

### 多个请求配置

在某些复杂场景的应用中，我们也可以配置多个请求，每个配置请求都是单一的实例对象。

```ts title="src/app.tsx"
import { defineRequestConfig } from '@ice/plugin-request/types';

export const requestConfig = defineRequestConfig([
  {
    baseURL: '/api',
    // ...RequestConfig 其他参数
  },
  {
    // 配置 request 实例名称，如果不配默认使用内置的 request 实例
    instanceName: 'request2',
    baseURL: '/api2',
    // ...RequestConfig 其他参数
  }
]);
```

使用示例：

```ts
import { request } from 'ice';

export default {
  // 使用默认的请求方法，即调用 /api/user 接口
  async getUser() {
    return await request({
      url: '/user',
    });
  },

  // 使用自定义的 request 请求方法，即调用接口 /api2/user
  async getRepo(id) {
    return await request({
      instanceName: 'request2',
      url: `/repo/${id}`,
    });
  },
};
```

## 异常处理

无论是拦截器里的错误参数，还是 `request` / `useRequest` 返回的错误对象，都符合以下类型：

```js
const error = {
  // 服务端返回错误状态码时则存在该字段
  response: {
    data: {},
    status: {},
    headers: {}
  },
  // 服务端未返回结构时则存在该字段
  request: XMLHttpRequest,
  // 一定存在，即 RequestConfig
  config: {
  },
  // 一定存在
  message: ''
}
```

## 高阶用法

### Mock 接口

项目开发初期，后端接口可能还没开发好或不够稳定，此时前端可以通过 Mock 的方式来模拟接口，参考文档 [本地 Mock 能力](../basic/mock.md)。

### 如何解决接口跨域问题

当访问页面地址和请求接口地址的域名或端口不一致时，就会因为浏览器的同源策略导致跨域问题，此时推荐后端接口通过 CORS 支持信任域名的跨域访问，具体请参考：

- [HTTP 访问控制（CORS）](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Access_control_CORS)
- [跨域资源共享 CORS 详解](https://www.ruanyifeng.com/blog/2016/04/cors.html)
- [Using CORS](https://www.html5rocks.com/en/tutorials/cors/)

### 根据环境配置不同的 baseURL

大部分情况下，前端代码里用到的后端接口写的都是相对路径如 `/api/getFoo.json`，然后访问不同环境时浏览器会根据当前域名发起对应的请求。如果域名跟实际请求的接口地址不一致，则需要通过 `request.baseURL` 来配置：

```ts title="src/app.tsx"
import { defineRequestConfig } from '@ice/plugin-request/types';

export const requestConfig = defineRequestConfig({
  baseURL: '//service.example.com/api',
});
```

结合[构建配置](../basic/env.md)即可实现不同环境使用不同的 baseURL：

```shell title=".env.local"
# The should not be committed.
BASEURL=http://localhost:9999/api
```

```shell title=".env.prod"
BASEURL=https://example.com/api
```

在 `src/app.tsx` 中配置 `request.baseURL`:

```ts title="src/app.tsx"
import { defineRequestConfig } from '@ice/plugin-request/types';

export const requestConfig = defineRequestConfig({
  baseURL: process.env.BASEURL,
});
```