@mock-sdk/core

基于 MirageJS 的轻量级 Mock HTTP 服务器 SDK，为开发和测试环境提供 API 响应拦截和模拟。

核心特性

- 开箱即用 - 无需复杂配置，一行代码启动 Mock 服务
- 灵活路由匹配 - 支持静态路由和动态参数（:id）URL 匹配
- 智能参数匹配 - 根据 URL 参数和查询参数返回不同响应
- 请求拦截记录 - 自动记录所有拦截的 HTTP 请求
- 数据持久化 - 请求数据自动保存到浏览器 localStorage
- 数据导入导出 - 支持 JSON 和 JavaScript 格式的数据导出
- 浏览器控制台接口 - 通过 window.__MIRAGE__ 在控制台管理服务
- 自动保存功能 - 可配置的自动保存定时器

安装

将mockjs文件引入
``javascript
import Mirage, { initMirage } from '@mock-sdk/core';
`
后续提供npm包直接进行安装

快速开始

$3

再mian.js中导入
`javascript
import Mirage from '@mock-sdk/core';

// 创建并初始化 Mock 服务
const mirage = new Mirage();
mirage.init();

// 现在所有 API 请求都会被拦截

// 关闭服务
mirage.shutdown();
`

$3

`javascript
import Mirage from '@mock-sdk/core';

const mirage = new Mirage();
mirage.init({
enabled: true, // 是否启用（默认检查 localStorage 或 NODE_ENV）
saveRequests: true, // 是否保存请求记录
autoUpdate: false, // 是否自动更新已存在的数据
storagePrefix: 'mirage_mock_', // localStorage 键前缀
mockData: null, // 主动引入mock数据
});
`

创建一个新的 Mock 服务实例。

$3

初始化并启动 Mock 服务。

参数：
- config (object) - 可选配置对象
- enabled (boolean) - 是否启用服务（默认基于环境）
- saveRequests (boolean) - 是否保存请求数据（默认 true）
- autoUpdate (boolean) - 是否自动更新已存在数据（默认 false）
- storagePrefix (string) - localStorage 键前缀（默认 'mirage_mock_'）
- mockData (object) - 预加载的 Mock 数据

例子：
`javascript
mirage.init({
enabled: true,
saveRequests: true,
autoUpdate: false
});
`

$3

关闭 Mock 服务，停止拦截请求。

`javascript
mirage.shutdown();
`

全局函数

$3

便捷函数，一次调用完成创建和初始化。

`javascript
import { initMirage } from '@mock-sdk/core';

const server = initMirage({
enabled: process.env.NODE_ENV === 'development'
});
`

$3

关闭指定的 Mock 服务实例。

`javascript
import { shutdownMirage } from '@mock-sdk/core';

shutdownMirage(server);
`

浏览器控制台接口

启动服务后，可以通过 window.__MIRAGE__ 对象在浏览器控制台进行高级操作。

$3

`javascript
// 禁用 Mock（刷新页面生效）
window.__MIRAGE__.disable();

// 启用 Mock（刷新页面生效）
window.__MIRAGE__.enable();
`

$3

`javascript
// 获取当前配置
console.log(window.__MIRAGE__.config);

// 查看所有 Mock 数据
console.log(window.__MIRAGE__.mockData);

// 获取服务器实例
const server = window.__MIRAGE__.server;
`

$3

`javascript
// 更新配置
window.__MIRAGE__.updateConfig({
autoUpdate: true,
saveRequests: false
});

// 切换自动更新
window.__MIRAGE__.toggleAutoUpdate();
`

$3

`javascript
// 导出 Mock 数据为 JSON 文件
window.__MIRAGE__.exportData();

// 导入 Mock 数据（需要选择文件）
window.__MIRAGE__.importData();

// 清空所有 Mock 数据
window.__MIRAGE__.clearData();

// 查看请求统计
window.__MIRAGE__.getStats();
`

$3

`javascript
// 配置自动保存
window.__MIRAGE__.configureAutoSave({
enabled: true,
format: 'js', // 'js' 或 'json'
interval: 5000, // 保存间隔（毫秒）
groupByUrl: true, // 是否按 URL 分组保存
savePath: 'src/mock/data/auto-generated/'
});

// 查看自动保存配置
window.__MIRAGE__.getAutoSaveConfig();

// 导出所有保存的请求
window.__MIRAGE__.exportAsFiles();

// 导出待处理的请求
window.__MIRAGE__.exportPending();
`

Mock 数据配置

Mock 数据通过 initMirage() 时传入，或通过全局变量 __MIRAGE__.mockData 访问。

$3

`javascript
{
'/api/endpoint': {
'GET': responseData,
'POST': responseData,
'PUT': responseData,
'DELETE': responseData,
},
'/api/users/:id': {
'GET': { / 响应 / }
}
}
`

$3

`javascript
const mockData = {
'/api/users': {
'GET': [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' }
],
'POST': { success: true, id: 3 }
}
};

mirage.init({ mockData });
`

$3

`javascript
const mockData = {
'/api/users/:id': {
'GET': {
'1': { id: 1, name: 'Alice' },
'2': { id: 2, name: 'Bob' },
'default': { error: 'User not found' }
}
}
};
`

当请求 /api/users/1 时返回第一条，/api/users/2 返回第二条，其他返回 default。

$3

`javascript
const mockData = {
'/api/posts': {
'GET': {
'status=published': [{ id: 1, title: 'Post 1' }],
'status=draft': [{ id: 2, title: 'Draft' }],
'default': []
}
}
};
`

请求 /api/posts?status=published 返回已发布文章，?status=draft 返回草稿。

$3

`javascript
const mockData = {
'/api/users/:id': {
'GET': {
'1': { id: 1, name: 'Alice' },
'error': {
status: 404,
body: { error: 'User not found' }
}
}
}
};
`

$3

`javascript
const mockData = {
'/api/login': {
'POST': (params, url, data) => {
if (data.password === '123456') {
return { token: 'abc123', success: true };
}
return { error: 'Invalid password' };
}
}
};
`

Vue 集成示例

`javascript
import Mirage from '@mock-sdk/core';
import App from './App.vue';
import Vue from "vue";
const app = createApp(App);

if (process.env.NODE_ENV === 'development') {
const mirage = new Mirage();
mirage.init({
enabled: true,
saveRequests: true
});


}

new Vue({
el: "#app",
router,
store,
render: (h) => h(App),
});
`

localStorage 控制

可以通过 localStorage 启用/禁用 Mock 服务，无需修改代码：

`javascript
// 禁用 Mock
localStorage.setItem('USE_MIRAGE_MOCK', 'false');

// 启用 Mock
localStorage.setItem('USE_MIRAGE_MOCK', 'true');

// 清除设置（恢复默认行为）
localStorage.removeItem('USE_MIRAGE_MOCK');
`

工作原理

1. 初始化时 - 检查是否应启用（基于 localStorage 或 NODE_ENV）
2. 启动时 - 使用 MirageJS 创建 mock 服务器
3. 拦截请求时 - 根据 URL 路径匹配 Mock 配置
4. 参数匹配时 - 支持 URL 参数和查询参数匹配
5. 保存请求时 - 将请求数据存储到 localStorage
6. 导出时 - 可导出为 JSON 或 JavaScript 文件

浏览器兼容性

所有代码使用 Babel 完整转译为 ES5，支持旧版浏览器。

构建

`bash


开发构建（watch 模式）

npm run dev

生产构建

npm run build:prod

构建输出

- dist/index.esm.js (ES Module)

- dist/index.cjs (CommonJS)

- dist/index.umd.js (UMD 浏览器全局)

`

常见问题

Q: Mock 服务没有启动？
A: 检查 init() 是否被调用，或查看 localStorage 中的 USE_MIRAGE_MOCK 值是否为 false。

Q: 如何在生产环境禁用？
A: 设置 localStorage.setItem('USE_MIRAGE_MOCK', 'false') 或检查 NODE_ENV。

Q: 请求数据保存在哪里？
A: 数据保存在浏览器 localStorage 中，以 mirage_mock_ 为键前缀。

Q: 如何自定义响应处理逻辑？
A: 使用函数格式的 Mock 数据配置，接收 (params, url, data)` 参数。