使用指南

Simple Boot Mock Server 是一个功能强大的 Mock 服务，支持基于 JavaScript (GraalJS) 的脚本引擎，允许您通过编写脚本来动态生成响应数据，实现高度灵活的 Mock 逻辑。

安装运行

1. 下载运行

下载最新版发行包 (Zip)：GitHub Releases

注意： 本地运行需要安装 Java 环境 (JRE/JDK 11+)。

1. 下载并解压 zip 文件。
2. 运行 bin/start.sh (Linux/macOS) 或 bin/start.bat (Windows)。

2. Docker 部署

使用 Docker 容器化部署是最简单快捷的方式：

docker run -d -p 9086:9086 fugary/simple-boot-mock-server:latest

Docker Hub 地址: fugary/simple-boot-mock-server

Docker 配置参数

支持以下环境变量配置 (-e)：

示例：使用 MySQL

docker run -d -p 9086:9086 \
  -e MOCK_DB_TYPE=mysql \
  -e MOCK_DB_MYSQL_SERVER=192.168.1.100 \
  -e MOCK_DB_USERNAME=root \
  -e MOCK_DB_PASSWORD=secret \
  fugary/simple-boot-mock-server:latest

基础入门

登录使用

默认启动后访问：http://localhost:9086

系统预置了两个账号：

修改密码

登录后请第一时间修改密码。点击右上角头像进入【个人资料】，清空旧密码并设置新密码即可。

Mock 分组

Mock 分组用于组织和管理接口。每个分组对应一组 API 接口。

新增分组

点击【新增】，填写【分组名称】。可以直接设置【代理地址】，当 Mock 规则未匹配时，请求会自动转发到该地址。

Mock 场景 (Scenarios)

场景 (Scenario) 用于在同一个 API 集合下管理不同的测试状态（如：正常、异常、超时等）。

• 由于不同的测试用例往往需要接口表现出不同的响应，通过创建并切换场景，可以一键切换整个分组下所有请求的激活响应状态。
• 分组始终会有一个默认场景，所有的请求响应都可以归属于特定场景。

激活场景

在场景管理列表中，点击【激活】按钮即可将该场景设为当前激活场景。在激活特定场景后，所有关联了该场景的响应都会生效；如果没有特定场景响应，则降级使用默认场景的响应。修改响应数据时，也可以指定它属于哪个具体的场景。

Mock 请求

一个 Mock 分组下可以包含多个 Mock 请求。请求由 路径、方法 和 匹配规则 唯一确定。

新建请求

填写请求路径（如 /api/user/info）和请求方法。

测试请求

保存后点击【测试】按钮可直接测试 API。

• 如果未配置响应且未配置代理：返回 404。
• 如果配置了代理：转发请求到代理地址。
• 如果配置了响应：返回配置的 Mock 数据。

Mock 响应

每个请求可以配置多个响应数据（例如：成功、失败、异常），便于覆盖不同测试场景。

新建响应数据

支持配置 HTTP 状态码、响应头、延迟时间等。响应体支持 JSON、XML 等格式。

默认响应与切换

当存在多条响应数据时，可以点击【设为默认】来指定当前生效的响应。这对于快速切换 "成功" / "失败" 场景非常有用。

历史版本

每次修改响应数据都会自动记录历史版本，支持版本对比和回滚。

请求对象 (Request)

响应对象 (Response)

JS & Mock.js 支持

系统内置 JavaScript 引擎 (基于 JDK ScriptEngine)，支持 ES6 语法 (箭头函数等)。

支持使用 Mock.js 语法生成随机数据。

Mock.js 模板

Mock.mock({
    "code": "success",
    "data|10": [{
        "id": "@integer(1, 100)",
        "city": "@city",
        "image": "@image('200x100')"
    }]
})

匹配规则

当同一个 URL 需要根据不同参数返回不同结果时，使用匹配规则。规则为 JS 表达式，返回 true 即匹配成功。

// 示例: 当参数 type 为 'vip' 且 header 中有 token 时匹配
request.params.type === 'vip' && request.headers.token

也支持使用自执行函数 (IIFE) 处理更复杂的逻辑：

(function () {
    if (request.params.name === "admin" && request.params.password === "123456") {
        return true;
    }
    return false;
}())

变量支持

在响应数据中，可以使用 request 对象获取请求参数，实现动态响应。

• request.body: 请求体对象
• request.params: 所有参数集合 (Path + Query)
• request.headers: 请求头

Mock.mock({
    "input_id": request.params.id,
    "input_name": request.body.name,
    "timestamp": Date.now()
})

XML 支持

XML 响应同样支持 JS 模板语法 and 变量替换。

<user>
    <id>{{request.params.id}}</id>
    <name>{{Mock.mock('@cname')}}</name>
</user>

内置函数

除了 Mock.js，系统还预置了大量工具函数，用于加密、解码和日期处理。

Fetch 异步请求

可以使用 fetch 请求第三方 API 并返回结果，支持 async/await。

获取 JSON 数据：

(async function () {
    const response = await fetch('https://httpbin.org/get?name=mock');
    const json = await response.json();
    return {
        original: json,
        processed: true,
        timestamp: Date.now()
    };
}())

获取并返回二进制图片：

(async function () {
    const response = await fetch('https://httpbin.org/image/png');
    return await response.blob();
}())

动态加载库 (CryptoJS)

通过 require 可以加载远程 JS 库，处理复杂的加密逻辑 or 使用第三方算法。

(async function () {
    // 加载 CryptoJS 库
    const CryptoJS = await require('https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js');
    
    const message = "hello world";
    const hash = CryptoJS.MD5(message).toString();
    const sha256 = CryptoJS.SHA256(message).toString();
    
    return {
        message: message,
        md5_hash: hash,
        sha256_hash: sha256
    };
}())

后置处理 (Post-Processor)

后置处理器允许您在响应生成后对其进行二次加工。支持修改状态码、头信息，或者将响应体从一种格式转换为另一种格式。

示例：将 XML 响应转换为 JSON

(function () {
  response.statusCode = 200;
  response.headers['Content-Type'] = 'application/json';
  return xml2Json(response.bodyStr);
}())

SSE 推送 (Event Stream)

对于需要模拟多消息推送 (Server-Sent Events) 的场景，可以返回一个特定的数组结构：

[{
  "data": "连接成功",
  "delay": 0
}, {
  "data": {"msg": "这是一条消息", "id": 1},
  "delay": 1000
}, {
  "data": "结束",
  "delay": 500
}]

系统会自动识别此格式并按照 delay 设定的毫秒数分段推送数据。