@mock-sdk/core

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

核心特性

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

安装

# 公网安装
npm i -d @mock-sdk/core

# 私有npm仓库 私有仓库安装步骤详见 npm私有仓库
npm i -d @plaformWeb/mock-sdk-core

使用方式

方式一: 在代码中导入 (传统方式)

// 公网
import Mirage, { initMirage } from '@mock-sdk/core';

// 私有仓库
import Mirage, { initMirage } from '@plaformWeb/mock-sdk-core';

方式二: Webpack Plugin (推荐)

在 webpack.config.js 中配置:

const MirageMockPlugin = require('@plaformWeb/mock-sdk-core/webpack-plugin');

module.exports = {
  plugins: [
    new MirageMockPlugin({
      enabled: process.env.NODE_ENV === 'development',
      saveRequests: true,
      namespace: '/api/v1',
      mockData: require('./mock/data.js')
    })
  ]
};

详细的 Webpack 使用说明请查看 WEBPACK_USAGE.md

快速开始

基础使用

再mian.js中导入

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

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

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

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

带配置的初始化

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 服务实例。

init(config)

初始化并启动 Mock 服务。

参数：

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

例子：

mirage.init({
  enabled: true,
  saveRequests: true,
  autoUpdate: false
});

shutdown()

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

mirage.shutdown();

全局函数

initMirage(config)

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

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

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

shutdownMirage(server)

关闭指定的 Mock 服务实例。

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

shutdownMirage(server);

浏览器控制台接口

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

启用/禁用服务

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

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

查看配置和数据

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

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

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

配置管理

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

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

数据管理

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

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

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

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

自动保存功能

// 配置自动保存
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();

自动刷新功能

自动刷新功能可以定时重新请求所有已保存的接口，获取最新的网络数据并更新localStorage。

// 配置自动刷新
window.__MIRAGE__.configureAutoRefresh({
  enabled: true,
  interval: 60000         // 刷新间隔（毫秒），默认60秒
});

// 查看自动刷新配置
window.__MIRAGE__.getAutoRefreshConfig();

// 手动刷新所有请求
window.__MIRAGE__.refreshAllRequests();

// 重新加载localStorage中的请求到刷新队列
window.__MIRAGE__.loadRequestsToRefreshQueue();

注意事项：

• 自动刷新会重新发起真实的网络请求，请确保后端服务可用
• FormData类型的请求会被自动识别和重新构造
• 刷新后的数据会自动覆盖localStorage中的旧数据
• 建议根据实际需求设置合理的刷新间隔，避免频繁请求

Mock 数据配置

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

数据结构

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

静态响应

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

mirage.init({ mockData });

URL 参数（动态路由）

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。

查询参数匹配

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 返回草稿。

错误响应

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

函数形式的响应处理

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

Vue 集成示例

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 服务，无需修改代码：

// 禁用 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，支持旧版浏览器。

构建

# 开发构建（watch 模式）
npm run dev

# 生产构建 (Rollup)
npm run build:prod

# Webpack 构建
npm run build:webpack

# 运行 Webpack 示例
npm run example:webpack

# 构建输出
# - dist/index.esm.js    (ES Module - Rollup)
# - dist/index.cjs       (CommonJS - Rollup)
# - dist/index.umd.js    (UMD 浏览器全局 - Rollup)
# - dist/index.js        (UMD - Webpack)

示例项目

项目提供了完整的示例代码:

• examples/webpack-example - 纯 JavaScript + Webpack 示例
• examples/vue-webpack-example - Vue 3 + Webpack 示例

运行示例:

# 运行 Webpack 示例
cd examples/webpack-example
npm install
npm run dev

# 运行 Vue 示例
cd examples/vue-webpack-example
npm install
npm run dev

常见问题

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) 参数。