@klweb/mock-server v2.0.0

@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 输入以下命令：

# 全局安装（任意目录下）
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 之后自动在当前项目根目录下创建，默认配置参数如下：

{
    "config": "./app.config.js",
    "mock": "./mock",
    "variable": "API_URL",
    "port": 3000,
    "log": false
}

以下是 @klweb/mock-server 的命令行参数说明：

-c,   --config    <filename>   应用配置文件
-m,   --mock      <dirname>    模拟数据目录
-v,   --variable  <name>       业务模块接口URL集合对象变量名
-p,   --port      <number>     模拟服务端口
-l,   --log       <boolean>    是否打印启动日志

上面每个参数分别有全称和缩写两种参数名，全称前缀 -- ，缩写前缀 - ，带前缀的参数只能用于命令行方式传递参数，.mockrc 文件中仅支持不带前缀全称参数名。

命令行方式如何传递参数，如：

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 指向的就是这个应用程序配置文件，且名称要一致、路径要正确。

// 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 发起请求：

axios.get(API_URL.mock, {
    	params: {}
    }).then(res => {
    	console.log(res)
    })

3. mock

mock 是存储 @klweb/mock-server 自动保存或其他手动添加的模拟数据 json 文件的目录位置，它也是必要的，.mockrc 配置文件中的 mock 指向的就是这个目录位置。

在项目中使用

在项目 package.json 文件中的 scripts 中添加脚本命令，如：

{
    ...
    "scripts": {
        "dev": "vite",
        "dev:mock": "run-p dev mock",
        "mock": "mock-serve",
        ...
    }
}

在终端命令行中输入 npm run dev:mock， 并行执行 dev 和 mock 脚本， 即启动项目的同时也启动了 @klweb/mock-server，两者在同一个进程中运行，结束进程则两者同时关闭服务。

如果你想单独进程持续化运行 @klweb/mock-server， 可以新建一个终端命令窗口，然后输入命令，如：

npm run mock

也可以通过命令行传递参数，如：

# 指定端口 3002
npm run mock -p 3002

全局使用

如果你通过 npm install @klweb/mock-server -g 全局安装了 @klweb/mock-server，则项目中无须再安装，只需在项目根目录创建 .mockrc、app.config.js、 mock。

全局安装并不会在你的项目根目录下自动创建 .mockrc，需手动创建并配置参数，如没有创建则默认程序预设配置

终端命令行切换至项目根目录，输入命令：

mock-serve

# 或命令行传递参数
mock-serve --port 3002 --log true

扩展能力

@klweb/mock-server 扩展能力在 KLWeb-App 开发框架中已有最佳实践应用，可参考源码，这里不再赘述。

• 自动保存 json 数据，写入本地磁盘
• HTTP Server 集成