mock-switch-webpack-plugin 1.1.1 → 1.3.0

package/README.md

@@ -1,305 +1,389 @@
-# Mock Switch Webpack Plugin
-
 <div align="center">
 
-![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
-![Webpack](https://img.shields.io/badge/webpack-%3E%3D5.0.0-green.svg)
+[![npm version](https://img.shields.io/npm/v/mock-switch-webpack-plugin)](https://www.npmjs.com/package/mock-switch-webpack-plugin)
 ![License](https://img.shields.io/badge/license-MIT-yellow.svg)
 
-**基于 webpack5 的开发环境接口 Mock 一键切换插件**
+**基于 webpack 的开发环境 API Mock 与代理管理插件**
 
 </div>
 
-## ✨ 特性
-
-### 🎯 核心功能
-- **🔄 浏览器端一键切换** - 页面内悬浮面板，Mock / 测试 / 生产环境无缝切换
-- **🔥 Mock 数据热更新** - 修改 Mock 文件立即生效，无需重启服务
-- **📝 自动记录真实接口** - 代理请求时自动记录返回，一键保存为 Mock 文件
-- **📂 自动路径匹配** - 根据接口路径自动查找对应 Mock 文件
-- **⚡ 零侵入式设计** - 纯 webpack 插件，无需修改业务代码
+在前端开发中，频繁切换接口环境（Mock/开发/生产）往往需要修改代码或重启服务。本插件通过 Webpack 与中间件技术，实现了一键可视化环境切换，让开发调试变得前所未有的流畅与高效。
 
-### 🎨 界面预览
-- 右下角悬浮切换按钮，状态指示灯（绿=Mock/黄=测试/红=生产）
-- 优雅的下拉面板，环境列表 + 已记录接口;
-- 点击即可保存真实接口返回为 Mock 文件
+## 核心特性
 
-## 🆚 与其他方案对比
+- **浏览器端一键切换**：页面右下角悬浮控制面板，支持 Mock / 开发 / 生产环境无缝切换，无需修改代码或重启服务；
+- **Mock 数据热更新**：修改 Mock 文件立即生效，无需重启服务；
+- **自动路径匹配**：根据接口路径自动查找对应的 Mock 文件；
+- **智能请求处理**：支持 POST/PUT/PATCH 请求 body 自动解析与转发；
+- **热重载友好**：全局单例模式，防止 CRA 热重载时重复创建实例，并且热重载不会丢失当前的环境状态，实现状态持久化；
+- **全平台兼容**：
+  - 支持 **CRA (Create React App)**、**Vue CLI** 及所有基于 Webpack 的项目；
+  - 兼容 Webpack 3/4/5 的 DevServer API 差异；
+- **开箱即用**：自动注入 UI 代码，自动配置路由，零配置即可体验；
 
-| 功能 | mock-switch-webpack-plugin | mocker-api | webpack-api-mocker | mockjs |
-|------|---------------------------|------------|-------------------|--------|
-| 浏览器端一键切换 | ✅ | ❌ | ❌ | ❌ |
-| Mock数据热更新 | ✅ | ✅ | ✅ | ❌ |
-| 自动记录真实接口 | ✅ | ❌ | ❌ | ❌ |
-| 一键保存为Mock | ✅ | ❌ | ❌ | ❌ |
-| 自动路径匹配 | ✅ | ✅ | ✅ | ❌ |
-| Webpack5支持 | ✅ | ✅ | ⚠️ | ❌ |
-| 零侵入集成 | ✅ | ⚠️ | ⚠️ | ❌ |
-| 动态Mock函数 | ✅ | ✅ | ✅ | ✅ |
-| 网络延迟模拟 | ✅ | ✅ | ❌ | ✅ |
+## 与其他方案VS对比
 
-> **为什么选择我们？** 现有方案都只解决了部分问题，本插件一站式解决「环境切换麻烦、Mock数据难维护、需要手动写Mock」三大痛点。
+| 功能 | mock-switch-webpack-plugin | mocker-api | 其他 |
+|------|---------------------------|------------|-------------------|
+| 浏览器可视化一键切换    | ✅ | ❌      | ❌        |
+| Mock数据热更新         | ✅ | ✅      | ❌需重启   |
+| 环境持久化             | ✅ | ❌      | ❌        |
+| POST Body 自动解析转发 | ✅ | ❌需手动 | ❌ 需手动 |
+| CRA 完美支持           | ✅ | ❌      | ❌        |
 
-## 📦 安装
+## 安装
 
 ```bash
 npm install mock-switch-webpack-plugin --save-dev
 # or
 yarn add mock-switch-webpack-plugin -D
-# or
-pnpm add mock-switch-webpack-plugin -D
 ```
 
-## 🚀 快速开始
+## 使用
 
-### 1. 配置 webpack.config.js
+### 方式一：原生 Webpack 项目
+
+**webpack\.config\.js**
 
 ```javascript
-const WebpackMockSwitchPlugin = require('mock-switch-webpack-plugin');
+const MockSwitchWebpackPlugin = require('mock-switch-webpack-plugin');
 
 module.exports = {
   // ... 其他配置
   plugins: [
-    new WebpackMockSwitchPlugin({
-      // Mock文件目录（相对项目根目录）
+    new MockSwitchWebpackPlugin({
       mockDir: './mock',
-      // 接口前缀，只拦截该前缀的请求
       apiPrefix: '/api',
-      // 环境配置
       environments: {
-        mock: { name: 'Mock环境', target: null },
-        test: { name: '测试环境', target: 'http://localhost:3000' },
-        prod: { name: '生产环境', target: 'https://api.yourdomain.com' }
-      },
-      // 自动记录真实接口返回
-      autoRecord: true,
-      // 开启热更新
-      hotReload: true
+        dev: {
+          name: '开发环境',
+          target: 'http://localhost:8080'
+        },
+        prod: {
+          name: '生产环境',
+          target: 'https://api.example.com'
+        }
+      }
     })
-  ],
-  devServer: {
-    // 插件会自动注入中间件，无需额外配置
-    hot: true,
-    open: true
-  }
+  ]
 };
 ```
 
-### 2. 创建 Mock 文件
+### 方式二：CRA \(Create React App\) 项目
 
-在项目根目录创建 `mock` 文件夹，按以下命名规则创建文件：
+CRA 项目需要同时配置 **webpack\.config\.js** 和 **setupProxy\.js** 两个文件。
 
-```
-mock/
-├── GET_user_list.json          # GET /api/user/list
-├── POST_user_login.js          # POST /api/user/login
-├── GET_user_1_detail.json      # GET /api/user/1/detail
-└── config.js                   # 其他配置
-```
+#### 步骤 1：配置 webpack\.config\.js
 
-#### 静态 Mock (JSON)
 
-```json
-// mock/GET_user_list.json
-{
-  "code": 0,
-  "message": "success",
-  "data": {
-    "list": [
-      { "id": 1, "name": "张三" },
-      { "id": 2, "name": "李四" }
+**webpack\.config\.js**
+
+```javascript
+const MockSwitchWebpackPlugin = require('mock-switch-webpack-plugin');
+
+module.exports = {
+  webpack: {
+    plugins: [
+      new MockSwitchWebpackPlugin({
+        autoRegisterMiddleware: false, // CRA 必须设为 false
+      })
     ]
-  },
-  "_delay": 500
-}
+  }
+};
 ```
 
-#### 动态 Mock (JS 函数)
+> 💡 **作用**：向打包输出注入客户端 UI 代码，实现浏览器右下角的环境切换悬浮面板。
+> 
+> 
+
+#### 步骤 2：配置 src/setupProxy\.js
+
+**src/setupProxy\.js**
 
 ```javascript
-// mock/POST_user_login.js
-module.exports = function(req, res) {
-  const { username, password } = req.body;
-  
-  if (username === 'admin' && password === '123456') {
-    return {
-      code: 0,
-      message: '登录成功',
-      data: { token: 'mock_' + Date.now() }
-    };
+const { createMockMiddleware } = require('mock-switch-webpack-plugin');
+
+module.exports = function(app) {
+  createMockMiddleware(app, {
+    mockDir: './mock',
+    apiPrefix: '/api',
+    environments: {
+      dev: {
+        name: '开发环境',
+        target: 'http://localhost:8080'
+      },
+      prod: {
+        name: '生产环境',
+        target: 'https://api.example.com'
+      }
+    }
+  });
+};
+```
+
+> 💡 **setupProxy\.js 作用说明**：
+> 
+> - CRA 开发服务器启动时自动加载此文件;
+> 
+> - 用于注册 Express 中间件，接管 API 请求;
+> 
+> - 实现 Mock 数据返回与代理转发逻辑;
+> 
+> - 使用单例模式，解决 CRA 热重载导致的重复实例问题;
+> 
+> 
+
+### 方式三：Vue CLI 项目
+
+**vue\.config\.js**
+
+```javascript
+const MockSwitchWebpackPlugin = require('mock-switch-webpack-plugin');
+
+module.exports = {
+  configureWebpack: {
+    plugins: [
+      new MockSwitchWebpackPlugin({
+        // 配置项
+      })
+    ]
   }
-  
-  return {
-    code: 401,
-    message: '用户名或密码错误'
-  };
 };
 ```
 
-### 3. 启动开发服务
+### 启动开发服务
 
 ```bash
 npm run start
 ```
 
-打开浏览器，你会看到右下角的悬浮切换按钮 🎉
+- 打开浏览器，你会看到右下角的悬浮切换按钮 
+- 点击按钮展开控制面板，实现环境实时切换 🎉
+
+## 配置说明
+### 完整配置项
+
+```javascript
+new MockSwitchWebpackPlugin({
+  /**
+   * Mock 文件存放目录
+   * @default './mock'
+   */
+  mockDir: './mock',
+
+  /**
+   * API 请求前缀
+   * @default '/api'
+   */
+  apiPrefix: '/api',
+
+  /**
+   * 是否启用 Mock 文件热更新
+   * @default true
+   */
+  hotReload: true,
+
+  /**
+   * 是否自动注册 DevServer 中间件
+   * @default true
+   * CRA 项目请设为 false，使用 createMockMiddleware
+   */
+  autoRegisterMiddleware: true,
+
+  /**
+   * 环境配置
+   * 内置 mock/dev/prod 三个环境，可自定义名称和目标地址
+   */
+  environments: {
+    mock: {
+      name: 'Mock环境',
+      target: null  // null 表示使用本地Mock文件
+    },
+    dev: {
+      name: '开发环境',
+      target: 'http://localhost:8080'
+    },
+    prod: {
+      name: '生产环境',
+      target: 'https://api.example.com'
+    }
+  }
+})
+```
+
+### environments 配置详解
 
-## ⚙️ 配置选项
+每个环境配置包含：
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `mockDir` | `string` | `./mock` | Mock 文件存放目录 |
-| `apiPrefix` | `string` | `/api` | 需要拦截的接口前缀 |
-| `environments` | `object` | 见下方 | 环境配置列表 |
-| `autoRecord` | `boolean` | `true` | 是否自动记录真实接口 |
-| `hotReload` | `boolean` | `true` | 是否开启 Mock 热更新 |
-| `port` | `number` | `38080` | 控制面板端口 |
+|参数|类型|说明|
+|---|---|---|
+|`name`|string|环境名称|
+|`target`|string \| null|代理目标地址，null 表示使用 Mock|
 
-### environments 默认配置
+**示例：自定义环境**
 
 ```javascript
-{
-  mock: { name: 'Mock环境', target: null },      // 本地Mock
-  test: { name: '测试环境', target: 'http://localhost:3000' },
-  prod: { name: '生产环境', target: 'https://api.example.com' }
+environments: {
+  mock: { name: 'Mock环境', target: null },
+  dev: { name: '开发环境', target: 'http://dev-api.example.com' },
+  prod: { name: '🔴 生产环境', target: 'https://api.example.com' }
 }
 ```
+### setupProxy\.js 配置详解（CRA 专用）
+
+#### 什么是 setupProxy\.js？
 
-## 📖 使用指南
+`setupProxy.js` 是 **Create React App** 官方约定的代理配置文件，位于 `src/` 目录下，CRA 开发服务器启动时会**自动加载**此文件。
 
-### 1. 环境切换
+#### createMockMiddleware 函数参数
 
-1. 点击右下角悬浮按钮打开面板
-2. 点击对应环境即可切换
-3. 状态指示灯会变色（绿/黄/红）
-4. 后续请求自动走对应环境
+```javascript
+createMockMiddleware(app, options)
+```
 
-### 2. 自动记录 & 保存 Mock
+|参数|类型|说明|
+|---|---|---|
+|`app`|Express|Express 应用实例，由 CRA 传入|
+|`options`|Object|配置选项，与插件构造函数参数一致|
 
-1. 切换到测试/生产环境
-2. 正常调用接口（插件会自动记录返回）
-3. 打开面板，在「已记录的接口」列表中
-4. 点击「保存」按钮，自动生成 Mock 文件
+## Mock 文件规范
 
-### 3. Mock 文件匹配规则
+### 目录结构
+
+```Plain Text
+your-project/
+├── mock/
+│   ├── GET_users.json          # GET /api/users
+│   ├── POST_users.js           # POST /api/users
+│   ├── GET_users_1.json        # GET /api/users/1
+│   └── GET_users_1_orders.js   # GET /api/users/1/orders
+└── src/
+```
+
+### 文件命名规则
 
 插件会按以下优先级查找 Mock 文件：
 
-1. `{METHOD}_{path}.json` - 如 `GET_user_list.json`
-2. `{path}.json` - 如 `user_list.json`
-3. `{METHOD}_{path}.js` - 如 `GET_user_list.js`
-4. `{path}.js` - 如 `user_list.js`
-5. 目录结构匹配 - 如 `/mock/user/list.json`
+1. `{METHOD}_{path}.json` \- 带方法的 JSON 文件
+
+2. `{path}.json` \- 不带方法的 JSON 文件
+
+3. `{METHOD}_{path}.js` \- 带方法的 JS 文件
 
-> 💡 提示：路径中的 `/` 会自动转换为 `_`
+4. `{path}.js` \- 不带方法的 JS 文件
 
-### 4. 高级功能
+> `path` 中的 `/` 会被替换为 `_`
+> 
+> 
 
-#### 模拟网络延迟
+### 静态 Mock \(JSON 文件\)
 
-在 JSON 中添加 `_delay` 字段：
+**mock/GET\_users\.json**
 
 ```json
 {
   "code": 0,
-  "data": {},
-  "_delay": 1000  // 延迟1秒返回
+  "message": "success",
+  "data": [
+    { "id": 1, "name": "张三" },
+    { "id": 2, "name": "李四" }
+  ],
+  "_delay": 500
 }
 ```
 
-#### 动态 Mock 函数
+### 动态 Mock \(JS 文件\)
 
-JS 文件导出函数，可访问 req/res 对象：
+**mock/POST\_users\.js**
 
 ```javascript
-module.exports = async (req, res) => {
-  // 获取查询参数
-  const { page, size } = req.query;
-  
-  // 获取请求体
-  const body = req.body;
-  
-  // 自定义响应头
-  res.setHeader('X-Custom-Header', 'mock');
+module.exports = function(req, res) {
+  // 可以访问请求参数
+  const { name, age } = req.body;
   
+  // 返回动态数据
   return {
     code: 0,
-    data: { page, size }
+    message: 'success',
+    data: {
+      id: Date.now(),
+      name,
+      age,
+      createdAt: new Date().toISOString()
+    },
+    _delay: 300  // 模拟网络延迟（毫秒）
   };
 };
 ```
 
-## 🔧 打包发布流程
-
-### 1. 发布到 npm
-
-```bash
-# 1. 登录 npm
-npm login
-
-# 2. 检查 package.json 配置
-# - name: 包名（需唯一）
-# - version: 语义化版本号
-# - main: 入口文件
-
-# 3. 发布
-npm publish
-
-# 发布私有包
-npm publish --access public
-```
-
-### 2. 版本管理
+### 特殊字段 `_delay`
 
-```bash
-# 补丁版本更新 (1.0.0 -> 1.0.1)
-npm version patch
+在返回数据中添加 `_delay` 字段可以模拟网络延迟：
 
-# 次版本更新 (1.0.0 -> 1.1.0)
-npm version minor
-
-# 主版本更新 (1.0.0 -> 2.0.0)
-npm version major
+```json
+{
+  "code": 0,
+  "data": {},
+  "_delay": 1000  // 延迟 1 秒返回
+}
 ```
 
-### 3. 本地测试
 
-```bash
-# 在插件目录
-npm link
 
-# 在测试项目
-npm link mock-switch-webpack-plugin
-```
 
-## ❓ 常见问题
 
-### Q: 为什么切换环境后需要刷新页面？
-A: 已发出的请求不会改变，新请求会走新环境。建议切换后刷新页面确保一致性。
 
-### Q: Mock 热更新不生效？
-A: 检查 `hotReload: true`，确保 Mock 文件在配置的 `mockDir` 目录下。
+### 2. 创建 Mock 文件
 
-### Q: 如何处理 body 参数？
-A: 需在 devServer 中配置 `devMiddleware: { writeToDisk: true }` 或添加 body-parser 中间件。
+在项目根目录创建 `mock` 文件夹，按以下命名规则创建文件：
 
-### Q: 支持 RESTful 动态路由吗？
-A: 目前支持精确匹配，动态路由建议使用 JS Mock 函数处理。
+```
+mock/
+├── GET_user_list.json          # GET /api/user/list
+├── POST_user_login.js          # POST /api/user/login
+├── GET_user_1_detail.json      # GET /api/user/1/detail
+└── config.js                   # 其他配置
+```
 
-## 📝 更新日志
+#### 静态 Mock (JSON)
 
-### v1.0.0 (2024-06-15)
-- ✅ 首次发布
-- ✅ 浏览器端环境切换面板
-- ✅ Mock 数据热更新
-- ✅ 真实接口自动记录
-- ✅ 一键保存为 Mock 文件
-- ✅ 自动路径匹配
+```json
+// mock/GET_user_list.json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "list": [
+      { "id": 1, "name": "张三" },
+      { "id": 2, "name": "李四" }
+    ]
+  },
+  "_delay": 500
+}
+```
 
-## 🤝 贡献
+#### 动态 Mock (JS)
 
-欢迎提交 Issue 和 Pull Request！
+```javascript
+// mock/POST_user_login.js
+module.exports = function(req, res) {
+  const { username, password } = req.body;
+  
+  if (username === 'admin' && password === '123456') {
+    return {
+      code: 0,
+      message: '登录成功',
+      data: { token: 'mock_' + Date.now() }
+    };
+  }
+  
+  return {
+    code: 401,
+    message: '用户名或密码错误'
+  };
+};
+```
 
-## 📄 License
+**如果这个插件对你有帮助，欢迎给个 ⭐ Star 哦！！！**
 
-MIT © Webpack Mock Switch Team
+[GitHub](https://github.com/shilimingY/mock-switch-webpack-plugin) • [Issues](https://github.com/shilimingY/mock-switch-webpack-plugin/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mock-switch-webpack-plugin",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "前端Mock神器！浏览器一键切换Mock/开发/生产环境的Webpack插件，支持接口代理、Mock数据热更新、POST请求自动转发等特性，零配置接入React/Vue等所有Webpack项目，彻底告别需手动修改代码来切换环境的低效开发方式。",
   "main": "dist/index.js",
   "scripts": {