npm package: @klweb/mock-server
Description: Mock data service based on Node + Express + Mock.js
Author: kunlun/zzh
Latest version: 2.0.1

# @klweb/mock-server

`@klweb/mock-server` 昆仑模拟数据服务应用中间件（`KL-MockServer`），是基于 `node` + `nodemon` + `express` + `mock.js` 编写开发的一款实用的 `node` 插件，它可以帮助开发者快速搭建和部署一个模拟数据服务器。

## 技术原理

`@klweb/mock-server` 通过使用 `node` 作为底层运行环境框架；`nodemon` 作为运行监控策略，监听文件更改自动重启数据服务；`express` 构建数据服务器以及使用 `mock.js` 语法动态生产数据，使得开发者能够轻松地创建 `API` 接口。同时，它还集成了 `cors`（跨源资源共享）功能，允许不同源的前端应用程序与数据服务器进行交互。

> 通过编写模拟数据规则和响应逻辑，模拟各种场景下的请求和响应，并且根据需要定制返回模拟数据的结果，前端开发者可以无需依赖后端接口服务器，从而进行视图交互开发和调试，解决项目开发中前后端数据联调的解耦。

## 插件特性

*   可全局或局部环境安装，配置简单
*   支持命令行方式运行服务程序并可传递参数
*   支持单独进程持续化运行
*   自动为前端应用程序提供数据服务
*   支持 `mock.js` 语法动态生产随机量级数据
*   服务端口被占用时可自动分配其它可用端口
*   实时监控数据文件更改，自动重启服务及状态反馈
*   可自动保存后端接口返回的 `json` 格式数据至本地磁盘
*   支持跨源资源共享，允许不同源的服务请求
*   支持离线闭环环境的数据演示服务
*   可在浏览器控制台 `network` 中查看数据请求信息

## 安装插件

`@klweb/mock-server` 支持全局和局部安装使用，`cmd` 输入以下命令：

```bash
# 全局安装（任意目录下）
npm install @klweb/mock-server -g

# 局部安装（项目根目录下）
npm install @klweb/mock-server -D
```

## 使用方法

`@klweb/mock-server` 的使用方法非常简单，只需通过 `npm install` 安装插件，然后在本地项目简单配置参数，即可在你的项目中启动一个模拟数据服务应用。

> 当开发者在使用 `@klweb/mock-server` 的时候，需要遵循它的一些规范约束，以达到最佳实践。

### 配置文件说明

`@klweb/mock-server` 默认关联两个配置文件和一个存储数据目录：`.mockrc`、`app.config.js`、`mock`，默认在项目根目录。当然，`@klweb/mock-server` 支持开发者通过 `.mockrc` 进行自定义配置。

#### 1. `.mockrc`

这是 `@klweb/mock-server` 的基本配置文件，非必要，但通过 `.mockrc` 可以更灵活的配置参数。
`.mockrc` 无须手动添加，它会在通过 `npm` 安装 `@klweb/mock-server` 之后自动在当前项目根目录下创建，默认配置参数如下：

```json
{
    "config": "./app.config.js",
    "mock": "./mock",
    "variable": "API_URL",
    "port": 3000,
    "log": false
}
```

以下是 `@klweb/mock-server` 的命令行参数说明：

```markdown
-c,   --config    <filename>   应用配置文件
-m,   --mock      <dirname>    模拟数据目录
-v,   --variable  <name>       业务模块接口URL集合对象变量名
-p,   --port      <number>     模拟服务端口
-l,   --log       <boolean>    是否打印启动日志
```

上面每个参数分别有全称和缩写两种参数名，全称前缀 `--` ，缩写前缀 `-` ，带前缀的参数只能用于命令行方式传递参数，`.mockrc` 文件中仅支持不带前缀全称参数名。<br>

命令行方式如何传递参数，如：

```bash
mock-serve -p 3001 -l true

# 或

mock-serve --port 3001 --log true

# 这个两个命令执行的结果是等价的
```
> **提示**：通过命令行方式传参，同时会写入覆盖 `.mockrc` 文件中的配置，`@klweb/mock-server` 的配置参数优先级：
 `程序预设配置` < `.mockrc`  < `命令行传参`

#### 2. `app.config.js`

应用程序配置文件，主要配置应用程序 `API` 接口地址和其它的全局配置，`@klweb/mock-server` 需要解析 `app.config.js` 文件中的接口配置信息自动生成模拟数据，因此 `app.config.js` 配置文件是应用程序必要的。

> `.mockrc` 配置文件中的 `config` 指向的就是这个应用程序配置文件，且名称要一致、路径要正确。

```typescript
// MockServer
const MOCK = 'http://localhost:3000' 

// 配置接口服务地址
const API_ROOT = MOCK

// 业务模块接口URL集合对象
const API_URL = {

	// Test Json
	'mock': API_ROOT + '/test/mock',
	
}
```

从以上 `app.config.js` 的配置信息中可以看到几个关键变量名，分别是 `MOCK`、`API_ROOT`、`API_URL`。

*   **`MOCK`**：`@klweb/mock-server` 启动后的服务地址
*   **`API_ROOT`**： 配置后端接口服务地址，如：`http://192.168.1.80:9000`。

> **规范约束**：
> 默认为 `API_ROOT`，如有多个接口服务地址，可增加一个变量，以 `API_ROOT` 开头加下横杠 `_` ，如： `API_ROOT_CUSTOM`，遵循格式正则：`/API_ROOT(_[A-Z|\d]+)?\s*?\+/g`，如声明不规范，可能会导致 `@klweb/mock-server` 无法正常解析配置文件而导致程序失效。

*   **`API_URL`**： 业务模块接口URL集合对象变量名，这个变量名必须与 `.mockrc` 配置文件中的属性 `variable` 的值一致。

如何使用 `API_URL` 声明的接口 `URL`, 如通过 `axios` 发起请求：

```typescript
axios.get(API_URL.mock, {
    	params: {}
    }).then(res => {
    	console.log(res)
    })
```

#### 3. `mock`

`mock` 是存储 `@klweb/mock-server` 自动保存或其他手动添加的模拟数据 `json` 文件的目录位置，它也是必要的，`.mockrc` 配置文件中的 `mock` 指向的就是这个目录位置。

### 在项目中使用

在项目 `package.json` 文件中的 `scripts` 中添加脚本命令，如：

```json
{
    "scripts": {
        "dev": "vite",
        "dev:mock": "run-p dev mock",
        "mock": "mock-serve"
    }
}
```

在终端命令行中输入 `npm run dev:mock`， 并行执行 `dev` 和 `mock` 脚本， 即启动项目的同时也启动了 `@klweb/mock-server`，两者在同一个进程中运行，结束进程则两者同时关闭服务。

> 如果你想单独进程持续化运行 `@klweb/mock-server`， 可以新建一个终端命令窗口，然后输入命令，如：

```bash
npm run mock
```

也可以通过命令行传递参数，如：

```bash
# 指定端口 3002
npm run mock -p 3002
```

### 全局使用

如果你通过 `npm install @klweb/mock-server -g` 全局安装了 `@klweb/mock-server`，则项目中无须再安装，只需在项目根目录创建 `.mockrc`、`app.config.js`、 `mock`。

> 全局安装并不会在你的项目根目录下自动创建 `.mockrc`，需手动创建并配置参数，如没有创建则默认程序预设配置

终端命令行切换至项目根目录，输入命令：

```bash
mock-serve

# 或命令行传递参数
mock-serve --port 3002 --log true
```

## 扩展能力

`@klweb/mock-server` 扩展能力在 `KLWeb-App` 开发框架中已有最佳实践应用，可参考源码，这里不再赘述。

*   自动保存 `json` 数据，写入本地磁盘
*   `HTTP Server` 集成