@forchange/mock/README.md

## Mock

[![npm version](https://img.shields.io/npm/v/@forchange/mock.svg)](https://www.npmjs.com/package/@forchange/mock)

mock 自定义规则、流程的数据模拟服务

## 特点

- mock 方式多样化，支持 json 和 function
- 隔离接口，容易维护，适合开源协作
- 接口联动处理，可根据业务流程自定义返回数据
- 文件路径即是路由和方法，接口唯一，更好的开发体验
- 支持 webSocket，连接、断开、主动推送消息 等操作可视化

## 快速开始

#### 安装

**安装 node 环境**

```
$ brew install node
```

**安装 mock 服务**

```
$ npm install -g @forchange/mock
```

#### 开始

**初始化：**

```
$ fmock init
```

```
$ cd <输入的文件名>
```

**启动：**

```
$ fmock
```

现在，访问 http://0.0.0.0:3839/user/info 查看接口

## 如何使用

#### 配置 config

config 文件是整个服务的配置文件 [详细说明](#config)

#### 添加 data

data 文件是接口对应的返回数据 [详细说明](#data)

#### 添加 rule

当我们构造 data 数据时，将会提供部分 [内部方法](#内部-rule)  
当你需要自定义 data 的返回数据时，可通过 rule 文件配置 [详细说明](#自定义-rule)

#### 添加 label

为了防止数据文件间的冲突，我们提供 label 标识 [详细说明](#label)

#### 添加 flow

当你需要进行接口间的数据联动时，可添加 flow 流程 [详细说明](#flow)

#### 示例目录结构

```tree
mock
├── config.js                           //config 配置入口
├── data                                //data 数据
│   └── ambassador
│       ├── courses
│       │   └── :id
│       │       └── :pay#get.js
│       ├── courses#get.js
│       ├── settlements
│       │   └── search.js
│       └── settlements#get.js
├── socket                              //socket 数据
│   ├── aaa.js
│   ├── access.js
│   ├── cun.js
│   ├── kkk
│   │   └── bbb.js
│   └── promise.js
└── rule.js                             //自定义规则
```

</br>

- data: 添加 [data](#data)
- socket: 添加 [socket](#socket)
- config.js: 配置 [config](#config)
- rule.js: 配置 [自定义规则](#自定义-rule)

## 命令

#### 常用指令

```
选项：
  create <path> [-l <label>] [-m <method>]  [-s]
    path           路径
    -l, --label    label 标签
    -s             是否为 socket 数据
    -m, --method   method of mock http

  init             快速开始

  -c, --config     config file of mock
  -h, --host       host of mock
  -p, --port       port of mock http
  -d, --directory  directory of mock http

  -v, --version    显示版本号
  --help           显示帮助信息

示例：
  fmock init
  fmock
```

#### 启动 mock 服务

```bash
$ fmock -c ./mock/config
```

#### 新建文件

默认创建 http 服务 data 文件  
当添加 `-s` 指令时创建 socket 服务 data 文件

```bash
$ fmock create ./aaa/bbb -m '方法名'
```

## config

#### 新建

添加 `config.js` 文件

#### 参数

<table>
   <tr>
      <td colspan="3">参数</td>
      <td>解释</td>
      <td>数据类型</td>
      <td>示例</td>
   </tr>
   <tr>
      <td colspan="3">host</td>
      <td>string</td>
      <td>ip</td>
      <td>‘0.0.0.0’</td>
   </tr>
   <tr>
      <td rowspan="7">http</td>
      <td colspan="2">port</td>
      <td>number</td>
      <td>http 服务端口</td>
      <td>3839</td>
   </tr>
   <tr>
      <td colspan="2">directory</td>
      <td>string</td>
      <td>http 数据文件路径</td>
      <td>‘./data’</td>
   </tr>
   <tr>
      <td colspan="2">middleware</td>
      <td>array</td>
      <td>自定义中间件</td>
      <td>[]</td>
   </tr>
   <tr>
      <td colspan="2">rule</td>
      <td>string</td>
      <td>自定义规则</td>
      <td>‘./rule.js’</td>
   </tr>
   <tr>
      <td rowspan="3">tls</td>
      <td>httpsPort</td>
      <td>number</td>
      <td>https 端口</td>
      <td>443</td>
   </tr>
   <tr>
      <td>key</td>
      <td>string</td>
      <td>密钥</td>
      <td></td>
   </tr>
   <tr>
      <td>cert</td>
      <td>string</td>
      <td>证书</td>
      <td></td>
   </tr>
   <tr>
      <td rowspan="2">socket</td>
      <td colspan="2">port</td>
      <td>number</td>
      <td>socket 服务端口</td>
      <td>3838</td>
   </tr>
   <tr>
      <td colspan="2">directory</td>
      <td>string</td>
      <td>socket 自定义回复文件</td>
      <td>‘./socket’</td>
   </tr>
   <tr>
      <td colspan="3">label</td>
      <td>string</td>
      <td>自定义 label</td>
      <td>‘xindongdong’</td>
   </tr>
</table>

#### 示例

```javascript
module.exports = {
  host: "0.0.0.0",
  http: {
    port: 8888,
    directory: "./data",
    middleware: ["a"],
    rule: "./rule.js",
    tls: {
      httpsPort: 443,
      key: "aaa",
      cert: "111"
    }
  },
  socket: {
    port: 3838,
    directory: "./socket"
  },
  label: "chenle"
};
```

## data

#### 新建

添加 `data` 文件夹，按照以下规则新建文件

#### 规则

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

#### 示例

`路由`：/ambassador/courses/:id/:pay  
`方法`：GET

```tree
mock
├── data
│   └── ambassador
│       ├── courses
│       │   └── :id
│       │       └── :pay#get.js
```

#### 数据定义

**JSON 数据**

我们将会直接获取到定义 data 数据。

**示例**

```javascript
exports.data = {
  errcode: 0,
  errmsg: "ok",
  data: {
    a: "@number",
    b: "2",
    c: [1, 2, 3],
    d: "@string",
    type: {
      __rule__: "@enum", // 枚举
      params: ["数组", "b", "c"]
    }
  }
};
```

**function**

在 function 中，你可以构造你想要的数据、状态等任何你需要的结构。

**示例**

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

## 内部 rule

在构造数据时，我们提供部分内部方法供你快速定义数据

#### 简单方法

**内置列表**

|     参数     |    解释    | 返回数据类型 |                 示例                 |
| :----------: | :--------: | :----------: | :----------------------------------: |
|     @id      |  id(8 位)  |    string    |               64669287               |
|    @name     |    姓名    |    string    |                李健龙                |
|  @province   |    省份    |    string    |                湖北省                |
| @phoneNumber |  电话号码  |    string    |             13888888888              |
|   @number    | 1-100 整数 |    number    |                  2                   |
|    @price    |    价格    |    number    |                388.00                |
|   @weekday   |    星期    |    string    |                Monday                |
|    @month    |    月份    |    string    |               January                |
| @recentDate  |  最近时间  |     date     |       2019-08-06T06:46:32.360Z       |
| @futureDate  |  未来时间  |     date     |                                      |
|  @pastDate   |  过去时间  |     date     |                                      |
|   @avatar    |    头像    |    string    |                                      |
|   @animals   |  动物图片  |    string    |                                      |
|  @sentences  |    段落    |    string    |                                      |
|    @lines    |  一行文本  |    string    |                                      |
|   @boolean   |   布尔值   |   boolean    |                 true                 |
|    @uuid     |    uuid    |    string    | 5c9b344b-a589-4efd-9c95-17508c0c0087 |

**示例**

```javascript
exports.rules = {
  books: {
    a: "@number",
    b: "2",
    c: [1, 2, 3],
    d: "@string"
  }
};
```

#### 复杂方法

复杂方法中，需要用参数进行配置，参数说明如下:

|     参数     | 解释 | 是否必填 | 数据类型 |  示例   |
| :----------: | :--: | :------: | :------: | :-----: |
| \_\_rule\_\_ | 标识 |    是    |  string  | '@list' |
|    params    | 参数 |    是    |  object  |         |

**内置列表**

| 参数  |     解释      | 返回数据类型  | 示例 |
| :---: | :-----------: | :-----------: | :--: |
| @enum |     枚举      | string/number |      |
| @list | 数组/数组对象 |     array     |      |

**列表详情**

`list`：列表方法，返回一定长度的列表，params 中定义以下参数

|  参数   |  解释  | 是否必填 | 数据类型 | 示例 |
| :-----: | :----: | :------: | :------: | :--: |
| number  |  数量  |    否    |  number  |  3   |
| payload | 子数据 |    是    | 任意类型 |      |

示例

```javascript
exports.rules = {
  classrooms: {
    __rule__: "@list",
    params: {
      number: 3,
      payload: {
        name: "@name"
      }
    }
  }
};
```

`enum`：枚举方法，返回定义的枚举之一，params 定义如下

|  参数  | 解释 | 是否必填 | 数据类型 | 示例 |
| :----: | :--: | :------: | :------: | :--: |
| params | 参数 |    是    |  array   |      |

示例

```javascript
exports.rules = {
  types: {
    __rule__: "@enum",
    params: [1, "@string", 3]
  }
};
```

## 自定义 rule

非必须项，不需要可跳过

#### 新建

添加 `rule.js` 文件

#### 添加规则

- 在 [config](#config) 中添加 `rule` 字段
- 通过 key-value 的方式添加规则，其中 key 为规则名，value 为方法

**简单规则**

既可以直接返回 number、 string 等**基本类型**，也可以返回 function**高级类型**。

基本类型示例

```javascript
module.exports = {
  houses: {
    a: 123,
    b: "@string"
  }
};
```

高级类型示例

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

**复杂规则**

当我们需要在方法中传递参数时，我们就需要使用**复杂规则**

**示例**

```javascript
module.exports = {
  houses: function(params) {
    let payload = params.payload;
    let number = params.number || 1;
    return {
      payload,
      number
    };
  }
};
```

此时的参数 `params` 便是我们在定义 [data 数据](#数据定义) 时添加的参数

**组合使用**

内置规则和自定义规则可以组合使用，进行数据构造

**示例**

定义规则:

```javascript
module.exports = {
  houses: function() {
    return {
      3: {
        __rule__: "@list",
        params: {
          payload: {
            a: "@avatar"
          }
        }
      },
      4: 4
    };
  }
};
```

组合使用：

```javascript
exports.data = {
  errcode: 0,
  errmsg: "",
  data: {
    a: "@houses",
    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]
              }
            }
          }
        }
      }
    }
  }
};
```

**接口作用域规则**

你可以在定义 [data 数据](#data) 时添加当前接口作用域下的自定义规则

```javascript
exports.rules = {
  a: function() {
    return 1;
  }
};

exports.data = {
  data: {
    name: "forchange",
    desc: "@a"
  }
};
```

## label

通过添加 label 标识，处理数据间的冲突问题
`label` 字段对 http 服务和 socket 服务均支持

#### 新建

在 [config](#config) 中添加 `label` 字段  
新建文档时添加 `-l` 指令指定 `label` 或者手动添加 `&<你的 label 名>`

#### 示例

新建

```
$ fmock create './aaa/bbb' -l 'xindongdong'
```

你将会生成

```tree
mock
├── data
│   └── aaa
│       ├── bbb#get&xindongdong.js
```

## flow

特殊情况下，可能需要在多个接口之间进行数据的联动处理，你可以在定义 `data` 数据时添加 `flow` 字段

#### 规定

- 当上一次请求和当前请求中 `flow` 定义的 `method`、`route` 匹配时，我们会返回 `flow` 中定义的 `data 数据`。
- 如果当前 `flow` 字段中没有 `data` 字段我们将会强制返回本次请求的 `data` 数据，并抛出警告。

#### 结构

[]{method, route, data}

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

#### 示例

```javascript
exports.flow = [
  {
    method: "get",
    route: "/ambassador/courses",
    data: {
      a: "/ambassador/courses",
      b: 234
    }
  },
  {
    method: "get",
    route: "/ambassador/settlements",
    data: {
      a: "/ambassador/settlements",
      b: 234
    }
  }
];
```

## middleware

#### 新建

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

#### 示例

```
middleware: [
    async (ctx, next) => {
        console.log('中间件运行 🐸🐸')
        await next()
    },
    async (ctx, next) => {
        console.log('中间件运行 🐸🐸')
        await next()
    }
]
```

## socket

#### 启动 socket 服务

你可以在 [config](#config) 中添加 `socket` 字段开启 socket 服务

#### 示例

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

#### 连接

当 socket 服务启动后，我们可以通过 `ws://host: 端口号/任意路由` 进行连接

#### 管理

当我们开启 socket 服务后，我们能通过 `host: 端口号/` 查看到所有 socket 连接情况  
你可以在此页面上进行连接、断开、发送消息等一系列操作，如图

<img src="https://git.forchange.cn/newbility/fe-doc/uploads/b3f833df1ff20477393eb211b7862fac/image.png" width="500px" height= "200px"/>

#### 添加自定义回复

你可以在 [config](#config) `socket` 字段中添加 `directory` 字段处理 socket 自定义回复文件

添加 `socket` 文件夹

**我们规定：**

- 文件路径即是你的路由（连接），如 `/aaa` 连接下对应的文件名为 `aaa.js`
- 一个文件对应一种回应方式

**示例**

```javascript
module.exports = async message => {
  return {
    name: "forchange",
    message: message
  };
};
```

#### 添加 label

参考 [label](#label)