npm package: @mock-sdk/core
Description: MirageJS-based Mock SDK for API development and testing
Author: mzy
Latest version: 1.3.2

# @mock-sdk/core

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

## 核心特性

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

## 安装

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

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

## 使用方式

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

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

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

### 方式二: Webpack Plugin (推荐)

在 `webpack.config.js` 中配置:

```javascript
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](./WEBPACK_USAGE.md)


## 快速开始

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

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

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

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

### 带配置的初始化

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

### init(config)

初始化并启动 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
});
```

### shutdown()

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

```javascript
mirage.shutdown();
```

## 全局函数

### initMirage(config)

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

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

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

### shutdownMirage(server)

关闭指定的 Mock 服务实例。

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

shutdownMirage(server);
```

## 浏览器控制台接口

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

### 启用/禁用服务

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

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

### 查看配置和数据

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

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

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

### 配置管理

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

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

### 数据管理

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

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

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

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

### 自动保存功能

```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();
```

### 自动刷新功能

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

```javascript
// 配置自动刷新
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` 访问。

### 数据结构

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

### 静态响应

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

mirage.init({ mockData });
```

### URL 参数（动态路由）

```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。

### 查询参数匹配

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

### 错误响应

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

### 函数形式的响应处理

```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

# 生产构建 (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 示例

运行示例:

```bash
# 运行 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)` 参数。