@forchange/mock/README.md

## 描述

 mock 用于本地开发使用模拟数据。   
 与其他线上 mock 平台不同，本地 mock 能够更好地把握和及时修改数据，拥有更好的体验和更高的效率。

#### 特点

- 长链接

- socket

- 自定义错误状态

- 接口之间的隔离

- 接口之间可以联动处理（数据传递）

- 简单易用，容易扩展

#### 相对于 oock 的改动

- 文件路径即是路由和方法，更好的体验

- 强制定义一个接口一个文件，防止出现不必要的麻烦

- 添加 socket 服务，支持连接、断开、服务端主动发送消息等

- 添加自定义数据结构，简单生成大量数据

- 添加数据传递处理


## 如何使用

#### 示例目录结构如下

<img src="https://git.forchange.cn/newbility/fe-doc/uploads/2218992756047b6b05228f9e3005e8f1/image.png" width="400px" height="300px"/>

</br>

- data: 数据文件
- config.js: [config 配置](#配置) 入口
- rule.js [自定义规则](#rule) 文件

#### 安装

`npm install @forchange/mock` 

or 

`yarn add @forchange/mock`


#### 添加服务配置

在 `package.json` -> `scripts` 添加     

`"mock": "node index.js -c config地址"`     

e.g： `"mock": "node index.js -c ./mock/config.js"`    

#### 添加 config 配置

添加 `mock` 文件夹，文件夹下添加 `config.js` 文件

按照 [配置](#配置) 进行配置

#### 添加 data 数据

👉 [mock](#mock)

#### 添加 rule 规则

mock 文件夹下添加 `rule.js` 文件

按照 [rule 规则](#rule) 添加自定义规则

#### 起服务

`yarn mock`


## 配置

#### 在 `mock` 文件夹下添加 'config.js' 文件

#### 文档说明，参考 👉

|    参数    |     解释     | 是否必填 | 数据类型 |   默认    |
| :--------: | :----------: | :------: | :------: | :-------: |
|    host    |              |    是    |  string  | '0.0.0.0' |
|    port    |     端口     |    是    |  number  |   3000    |
| directory  | data 文件夹  |    是    |  string  |           |
|   socket   | socket 配置  |    否    |  object  |    {}     |
| middleware | 自定义中间件 |    否    |  array   |           |
| rule | 自定义规则文件 |    否    |  string   |     './rule.js'      |
|   watch    |     监听     |    否    | boolean  |           |
| httpsPort  |  https端口   |    否    |  String  |    443    |
|    tls     |              |    否    | boolean  |   false   |
|    key     |   私钥文件   |    否    |  string  |           |

## mock

在 oock 的基础上我们改变了文件分层以及路由处理方式  

**我们强制定义了以下几条规则：**

- 一个接口一个文件
- 文件路径即路由和方法

**添加文件方式**

我们通过文件的层级划分来定义路由和方法

例如：如果你的路由为 `/v2/address/email` 请求方法为 `GET`
那么你的文件层级应该如下：  

<img src="https://git.forchange.cn/newbility/fe-doc/uploads/8e91d5eb1a4cacd87ec3c1e0be55d4ca/image.png" />

</br >   

> 接口的最后一级路径加上请求方法即是文件名
> 没有请求方法将不会解析成功


**我们有两种数据定义方式： data 数据、 function 中间件**

<!-- > 在 [koa-router](https://www.npmjs.com/package/koa-router#module_koa-router--Router+param) 处理路由时，参数为 middleware ,所以传入 data 数据我们将会在内部处理为 midddleware 中间件 -->

- data 数据

直接定义 data 数据。我们将会获取到数据中的 data 字段，并且返回。

```
module.exports = {
    flow: [{
        method: 'get',
        route: '/ambassador/courses',
        data : {
            a:'abc',
            email: 'abc@forchange.tech',
            b:123
        }
    }],
    data: {
        a: '@number',
        b: '2',
        c: [1, 2, 3],
        d: '@string',
        type: {
            // 枚举
            __rule__: "@enum",
            payload: ['数组', 'b', 'c']
        },
    },
}
```

在上面的例子中我们使用了自定义的 rule 规则进行数据构造，请参考 👉：[rule 规则](#rule)

> 如果你不需要使用 rule 规则进行定义，按照常规定义数据即可

如果你希望进行数据联动，在访问一个接口的前提下访问当前接口获取特定数据，请参考 [flow](#flow)

- function 中间件

```
module.exports = async (ctx, next) => {
    ctx.status = 200
    ctx.body = {
        aaa: 123,
        bbb: 234
    }
    await next()
}
```

## socket

#### 如果你想开启 socket 服务，你可以在 [config 配置](#配置) 中添加 `socket` 字段开启 socket 服务

```
socket: {
    port: 端口号
}
```

🚗🚗🚗☁️☁️☁️未完待续...

## rule

#### 你可以在定义 `data` 数据时添加自定义的 `rule` 文件进行规则定义。

:::tip
此时你需要在 [配置](#配置) 中添加 `rule` 配置，不然将不会生效   
如果自定义字段没有找到规则我们将不会解析   
如果自定义方法和内置方法相同我们将会进行强制覆盖
:::

e.g:

```
module.exports = {
  houses: function(req) {
    return {
        3:3,
        4:4
    };
  }
};
```

#### 在定义 data 数据是便可使用 rule 规则进行数据构造

```
module.exports = {
    flow: [{
        method: 'get',
        route: '/ambassador/courses',
        data : {
            a:'abc',
            email: 'abc@forchange.tech',
            b:123
        }
    }],
    data: {
        a: '@number',
        b: '2',
        c: [1, 2, 3],
        d: '@string',
        type: {
            // 枚举
            __rule__: "@enum",
            payload: ['数组', 'b', 'c']
        },
        orders: {
            name: "cheaa",
            ids: {
                // 原子数组
                __rule__: "@list",
                number: 10,
                payload: {
                    id: '@number',
                    name: '@string',
                    rooms: [1, 3],
                    books: {
                        __rule__: "@list",
                        number: 4,
                        payload: {
                            tags: {
                                __rule__: "@enum",
                                payload: [1,2,3]
                            }
                        }
                    }
                }
            }
        },
    },
}
```

### 对于复杂类型，我们需要进行特殊的规则处理

#### 内部方法表：
|    参数    |     解释   | 数据类型 | 
| :--------: | :----------: | :------: | 
|    @string    |    字符串   |  string  | 
|    @address   |    地址    |  string  | 
|    @name   |    姓名    |  string  | 
|    @month    |     月份    |  string  | 
|    @number    |     数字    |  number  | 
|    @enum    |     枚举    |  array  | 
|    @list    |     数组/数组对象    |  array  | 

## flow

#### 你可以在定义 `data` 数据时添加 `flow`  字段来处理接口之间的联动  

我们规定，当你当前请求的上一次请求和 `flow` 中定义的 `method`、`route` 相匹配，将会将 `data` 中的数据作为该次请求的返回。  

如果当前 `flow` 字段中没有 `data` 我们将会强制返回本次请求的 `data` 数据，并抛出警告。

> flow 字段类型为 array

|    参数    |     解释     | 是否必填 | 数据类型 | 
| :--------: | :----------: | :------: | :------: |
|    method   |     方法    |    是    |  string  | 
|    route    |     路由     |    是    |  string  |
|    data    |     强制返回的数据     |    是    |  object  | 

```
flow: [{
        method: 'get',
        route: '/ambassador/courses',
        data : {
            a:faker.name.findName(),
            email: faker.internet.email(),
            randomCard: faker.database.type(),
            b:faker.date.month()
        }
    }, {
        method: 'get',
        route: '/ambassador/settlements',
        data: {
            a: '/ambassador/settlements',
            b: 234
        }
    }],
```

## middleware 中间件

#### 如果你需要自定义中间件，你需要在 [配置](#配置) 中添加 `middleware` 字段

> middleware 字段类型为 array

我们将会在 koa 服务中解析中间件，所以 array 数组的每一项均是一个 middleware

## example