# 请求层基类 Fetcher.js

- [请求层基类 Fetcher.js](#请求层基类-fetcherjs)
  - [功能说明](#功能说明)
  - [引用方法](#引用方法)
  - [构造函数](#构造函数)
  - [主要方法](#主要方法)
  - [响应处理](#响应处理)
    - [处理流程](#处理流程)
    - [前端统一响应数据格式](#前端统一响应数据格式)
    - [前端统一响应状态码](#前端统一响应状态码)
  - [请求调用](#请求调用)

## 功能说明

类 Fetcher 是一个用于处理 HTTP 请求的基类，包含了多种方法来简化和统一请求的处理，请求层的每个请求集，都必须继承此类

## 引用方法

```js
import {
    Fetcher
} from '@components/bases/Fetcher';
```

## 构造函数

构造函数接受一个配置对象 options 作为参数，包含如下属性：
* **urlPrefix** 数组，包含两项，第一项为本地 Mock 的 URL 前缀，第二项为服务器接口的前缀

```js
class FCommon extends Fetcher {

    constructor() {
        // 构造函数使用示例
        super({
            urlPrefix: ['/api/order/', '/mini/order/'],
        });
    }
}
```

## 主要方法

```js
/**
 * 拼写 URL 地址
 * @param {String} devSuffix - 开发环境URL后缀
 * @param {String} serSuffix - 服务器环境URL后缀
 * @return {String} 拼接后的 URL 地址（不含域名）
 */
spellURL(devSuffix, serSuffix) {}

/**
 * 发送 POST 请求，query 的简写
 * @param {String} url - 请求的 URL
 * @param {*} data - 请求参数
 * @param {Object} [options] - 请求选项
 * @return {Promise<any>} 返回一个 Promise 对象，解析为响应数据
 */
post(url, data, options = {}) {}

/**
 * 基础 AJAX 请求
 * @param {String} type - 请求类型（GET 或 POST）。
 * @param {String} url - 请求的 URL。
 * @param {*} [data] - 请求参数。
 * @param {Object} [options] - 请求选项。
 * @return {Promise<any>} 返回一个 Promise 对象，解析为响应数据。
 */
query(type, url, data = null, options = {}) {}

/**
 * 下划线字符串转小驼峰
 * @param {String} str - 下划线字符串
 * @return {String} 转换后的驼峰字符串
 */
stringToCamel(str) {}

/**
 * 小驼峰字符串转下划线
 * @param {String} str - 小驼峰字符串
 * @return {String} 转换后的下划线字符串
 */
stringToUnderline(str) {}

/**
 * 驼峰与下划线命名模式转换
 * @param {String} type - 'camel' 或 'underline'
 * @param {Object} json - JSON 对象
 * @return {Object} 转换后的 JSON 对象
 */
transKeyName(type, json) {}
```

说明：
* spellURL：拼接URL时，会根据是否处于本地开发场景，来选择不同的 URL 前缀
* query：如果在小程序中，会自动存取 cookies

例如：

```js
class FCommon extends Fetcher {

    // 请求方法使用示例：获取用户基本信息（提供给数据控制层中调）
    getUserInfo(id) {
        const url = this.spellURL('getUserInfo', 'user/user_info');
        const send = {
            id
        };
        return this.post(url, send);
    }
}
```

## 响应处理

### 处理流程

1. query 方法调用 Taro.request 发送请求
2. 收到响应后，先检测响应数据格式，发现其他类型的响应格式时，会自动转换为：**前端统一响应数据格式**
3. 根据响应格式
    - 如果成功，将响应内容，回传给数据控制层
    - 如果失败，直接失败提示，回传空内容给数据控制层
4. 将响应内容传给数据控制层之前，会进行如下处理
    - 将数据中的键名，转换为的驼峰
    - 将数据中的内容，如果是常规数字的字符串，转为数值

### 前端统一响应数据格式

格式如下：

```
{
    state: { // 状态
        code, // 状态码
        msg // 状态消息
    }, 
    data: { // 实际数据，必须是 Object
    }
}
```

例如：

```json
{
    "state": {
        "code": 2000,
        "msg": "OK"
    },
    "data": {
        "id": 1,
        "name": "Tevin"
    }
}
```

注意，为了保证接口数据的扩展性，data 只能接 Object 类型，禁止接其他类型

### 前端统一响应状态码

| 状态码 | 意义                                                   |
| ------ | ------------------------------------------------------ |
| 2000   | 通用请求成功                                           |
| 2001   | 请求成功，但是没有数据，弹窗提示 msg（仅特殊情况使用） |
| 5000   | 通用请求失败，弹窗提示 msg                             |
| 9001   | 登录已过期，返回登录页                                 |
| 9002   | 已登录但没有操作权限，弹窗提示 msg                     |

## 请求调用

请求层的每一个请求集，都会实例化自身作为全局单例（数据控制层无需再示例化）  
比如说，请求集 FCommon 会实例化自身为 $fetchCommon

```js
import {
    $fetchCommon
} from '@fetchers/FCommon';

export class PPageName extends Pilot {

    // 在数据控制层中，发请求示例
    onLoadUserInfo() {
        Taro.showLoading();
        $fetchCommon.getUserInfo(this.userId)
            .then(res => {
                Taro.hideLoading();
                if (!res) {
                    return;
                }
                this.userInfo = res || {};
            });
    }

}
```