mock-switch-webpack-plugin 1.1.1 → 1.2.0

package/README.md

@@ -1,44 +1,68 @@
-# Mock Switch Webpack Plugin
+# Mock Switch Webpack Plugin README
 
-<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)
-![License](https://img.shields.io/badge/license-MIT-yellow.svg)
 
-**基于 webpack5 的开发环境接口 Mock 一键切换插件**
+**前端开发环境 API Mock 与代理管理插件**
 
-</div>
+一键切换 Mock / 开发 / 生产环境，Mock 数据热更新，无需重启服务
 
-## ✨ 特性
+\[特性\]\(\#\-核心特性\) • \[安装\]\(\#\-安装\) • \[快速开始\]\(\#\-快速开始\) • \[配置说明\]\(\#\-配置说明\) • \[Mock 规范\]\(\#\-mock\-文件规范\)
 
-### 🎯 核心功能
-- **🔄 浏览器端一键切换** - 页面内悬浮面板，Mock / 测试 / 生产环境无缝切换
-- **🔥 Mock 数据热更新** - 修改 Mock 文件立即生效，无需重启服务
-- **📝 自动记录真实接口** - 代理请求时自动记录返回，一键保存为 Mock 文件
-- **📂 自动路径匹配** - 根据接口路径自动查找对应 Mock 文件
-- **⚡ 零侵入式设计** - 纯 webpack 插件，无需修改业务代码
 
-### 🎨 界面预览
-- 右下角悬浮切换按钮，状态指示灯（绿=Mock/黄=测试/红=生产）
-- 优雅的下拉面板，环境列表 + 已记录接口;
-- 点击即可保存真实接口返回为 Mock 文件
 
-## 🆚 与其他方案对比
+## 🎯 核心特性
 
-| 功能 | mock-switch-webpack-plugin | mocker-api | webpack-api-mocker | mockjs |
-|------|---------------------------|------------|-------------------|--------|
-| 浏览器端一键切换 | ✅ | ❌ | ❌ | ❌ |
-| Mock数据热更新 | ✅ | ✅ | ✅ | ❌ |
-| 自动记录真实接口 | ✅ | ❌ | ❌ | ❌ |
-| 一键保存为Mock | ✅ | ❌ | ❌ | ❌ |
-| 自动路径匹配 | ✅ | ✅ | ✅ | ❌ |
-| Webpack5支持 | ✅ | ✅ | ⚠️ | ❌ |
-| 零侵入集成 | ✅ | ⚠️ | ⚠️ | ❌ |
-| 动态Mock函数 | ✅ | ✅ | ✅ | ✅ |
-| 网络延迟模拟 | ✅ | ✅ | ❌ | ✅ |
+### ✨ 浏览器端一键环境切换
 
-> **为什么选择我们？** 现有方案都只解决了部分问题，本插件一站式解决「环境切换麻烦、Mock数据难维护、需要手动写Mock」三大痛点。
+- 右下角悬浮控制面板，可视化切换环境
+
+- 实时状态显示，不同环境对应不同颜色标识
+
+- 无需修改代码或重启服务
+
+### 🔥 Mock 数据热更新
+
+- 修改 Mock 文件立即生效，无需重启 Webpack DevServer
+
+- 自动清除 require 缓存，实时加载最新数据
+
+- 支持开发过程中快速调试接口
+
+### 📦 开箱即用，零配置
+
+- 支持 **CRA \(Create React App\)**、**Vue CLI**、**原生 Webpack** 等所有项目
+
+- 兼容 Webpack 3/4/5 全版本
+
+- 兼容 Webpack 打包发布模式
+
+### 🔌 智能请求处理
+
+- POST/PUT/PATCH 请求 body 自动解析与转发
+
+- 支持 JSON 和表单格式请求
+
+- 自动移除 API 前缀，无缝代理转发
+
+### 🛡️ 热重载友好
+
+- 全局单例模式，防止 CRA 热重载时重复创建实例
+
+- 环境状态跨热重载持久化
+
+- 解决全局状态隔离问题
+
+## 🆚 方案对比
+
+|特性|Mock Switch|mockjs|http\-proxy\-middleware|
+|---|---|---|---|
+|浏览器可视化切换|✅|❌|❌|
+|Mock 数据热更新|✅|❌|\-|
+|无需重启服务|✅|❌|❌|
+|多环境一键切换|✅|❌|✅|
+|POST Body 自动解析|✅|❌|⚠️ 需手动|
+|CRA 友好支持|✅|⚠️|⚠️|
+|打包兼容|✅|✅|✅|
 
 ## 📦 安装
 
@@ -52,254 +76,401 @@ 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\) 项目
+
+CRA 项目需要同时配置 **webpack\.config\.js** 和 **setupProxy\.js** 两个文件。
+
+#### 步骤 1：配置 webpack\.config\.js
+
+使用 `craco` 或 `react-app-rewired` 覆盖 Webpack 配置：
 
-在项目根目录创建 `mock` 文件夹，按以下命名规则创建文件：
+**craco\.config\.js** 或 **config\-overrides\.js**
 
+```javascript
+const MockSwitchWebpackPlugin = require('mock-switch-webpack-plugin');
+
+module.exports = {
+  webpack: {
+    plugins: [
+      new MockSwitchWebpackPlugin({
+        autoRegisterMiddleware: false,  // CRA 必须设为 false
+        hotReload: true
+      })
+    ]
+  }
+};
 ```
-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                   # 其他配置
+
+> 💡 **作用**：向打包输出注入客户端 UI 代码，实现浏览器右下角的环境切换悬浮面板。
+> 
+> 
+
+#### 步骤 2：配置 src/setupProxy\.js
+
+**src/setupProxy\.js**（CRA 官方约定的代理配置文件）
+
+```javascript
+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'
+      }
+    }
+  });
+};
 ```
 
-#### 静态 Mock (JSON)
+> 💡 **setupProxy\.js 作用说明**：
+> 
+> - CRA 开发服务器启动时自动加载此文件
+> 
+> - 用于注册 Express 中间件，接管 API 请求
+> 
+> - 实现 Mock 数据返回与代理转发逻辑
+> 
+> - 使用单例模式，解决 CRA 热重载导致的重复实例问题
+> 
+> 
 
-```json
-// mock/GET_user_list.json
-{
-  "code": 0,
-  "message": "success",
-  "data": {
-    "list": [
-      { "id": 1, "name": "张三" },
-      { "id": 2, "name": "李四" }
+### 方式三：Vue CLI 项目
+
+**vue\.config\.js**
+
+```javascript
+const MockSwitchWebpackPlugin = require('mock-switch-webpack-plugin');
+
+module.exports = {
+  configureWebpack: {
+    plugins: [
+      new MockSwitchWebpackPlugin({
+        // 配置项
+      })
     ]
-  },
-  "_delay": 500
-}
+  }
+};
 ```
 
-#### 动态 Mock (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() }
-    };
+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'
+    }
   }
-  
-  return {
-    code: 401,
-    message: '用户名或密码错误'
-  };
-};
+})
 ```
 
-### 3. 启动开发服务
+### environments 详解
 
-```bash
-npm run start
+每个环境配置包含：
+
+|参数|类型|说明|
+|---|---|---|
+|`name`|string|环境显示名称，支持 emoji|
+|`target`|string \| null|代理目标地址，null 表示使用 Mock|
+
+**示例：自定义环境**
+
+```javascript
+environments: {
+  mock: { name: '🟢 Mock环境', target: null },
+  test: { name: '🔵 测试环境', target: 'http://test-api.example.com' },
+  pre: { name: '🟡 预发环境', target: 'http://pre-api.example.com' },
+  prod: { name: '🔴 生产环境', target: 'https://api.example.com' }
+}
 ```
 
-打开浏览器，你会看到右下角的悬浮切换按钮 🎉
+---
+
+### setupProxy\.js 配置详解（CRA 专用）
+
+#### 什么是 setupProxy\.js？
 
-## ⚙️ 配置选项
+`setupProxy.js` 是 **Create React App** 官方约定的代理配置文件，位于 `src/` 目录下，CRA 开发服务器启动时会**自动加载**此文件。
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `mockDir` | `string` | `./mock` | Mock 文件存放目录 |
-| `apiPrefix` | `string` | `/api` | 需要拦截的接口前缀 |
-| `environments` | `object` | 见下方 | 环境配置列表 |
-| `autoRecord` | `boolean` | `true` | 是否自动记录真实接口 |
-| `hotReload` | `boolean` | `true` | 是否开启 Mock 热更新 |
-| `port` | `number` | `38080` | 控制面板端口 |
+#### 为什么 CRA 需要 setupProxy\.js？
 
-### environments 默认配置
+1. **CRA 隐藏了 webpack\.config\.js**，无法直接修改 DevServer 配置
+
+2. **HTTP 代理中间件**必须在 Express 应用层注册
+
+3. **Mock 逻辑**需要在请求到达 React 之前拦截处理
+
+#### createMockMiddleware 函数参数
 
 ```javascript
-{
-  mock: { name: 'Mock环境', target: null },      // 本地Mock
-  test: { name: '测试环境', target: 'http://localhost:3000' },
-  prod: { name: '生产环境', target: 'https://api.example.com' }
+createMockMiddleware(app, options)
+```
+
+|参数|类型|说明|
+|---|---|---|
+|`app`|Express|Express 应用实例，由 CRA 传入|
+|`options`|Object|配置选项，与插件构造函数参数一致|
+
+#### 内部工作原理
+
+```javascript
+function createMockMiddleware(app, options) {
+  // 1. 单例模式：热重载复用已有实例
+  if (_pluginSingleton) return _pluginSingleton;
+  
+  // 2. 创建插件实例（关闭自动注册中间件）
+  _pluginSingleton = new MockSwitchWebpackPlugin({
+    ...options,
+    autoRegisterMiddleware: false
+  });
+  
+  // 3. 手动注册路由和中间件
+  _pluginSingleton.registerRoutesWithBodyParser(app);
+  
+  return _pluginSingleton;
 }
 ```
 
-## 📖 使用指南
+#### ✅ 关键配置要点
+
+- **必须**设置 `autoRegisterMiddleware: false`
 
-### 1. 环境切换
+- **必须**使用 `createMockMiddleware` 而非直接 `new MockSwitchWebpackPlugin()`
 
-1. 点击右下角悬浮按钮打开面板
-2. 点击对应环境即可切换
-3. 状态指示灯会变色（绿/黄/红）
-4. 后续请求自动走对应环境
+- **支持**热重载：全局单例 \+ 状态持久化
 
-### 2. 自动记录 & 保存 Mock
+- **自动**注册 express\.json \(\) 和 urlencoded 中间件
 
-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. 高级功能
+4. `{path}.js` \- 不带方法的 JS 文件
 
-#### 模拟网络延迟
+> `path` 中的 `/` 会被替换为 `_`
+> 
+> 
 
-在 JSON 中添加 `_delay` 字段：
+### 静态 Mock \(JSON 文件\)
+
+**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  // 模拟网络延迟（毫秒）
   };
 };
 ```
 
-## 🔧 打包发布流程
+### 特殊字段 `_delay`
 
-### 1. 发布到 npm
+在返回数据中添加 `_delay` 字段可以模拟网络延迟：
 
-```bash
-# 1. 登录 npm
-npm login
+```json
+{
+  "code": 0,
+  "data": {},
+  "_delay": 1000  // 延迟 1 秒返回
+}
+```
 
-# 2. 检查 package.json 配置
-# - name: 包名（需唯一）
-# - version: 语义化版本号
-# - main: 入口文件
+## 🎨 控制面板预览
 
-# 3. 发布
-npm publish
+启动项目后，浏览器右下角会出现悬浮按钮：
 
-# 发布私有包
-npm publish --access public
-```
+- 🟢 **绿色** \- Mock 环境
 
-### 2. 版本管理
+- 🟡 **黄色** \- 开发环境
 
-```bash
-# 补丁版本更新 (1.0.0 -> 1.0.1)
-npm version patch
+- 🔴 **红色** \- 生产环境
+
+点击按钮展开面板，点击对应环境即可实时切换。
+
+## 🔧 API 接口
+
+插件自动注册以下控制接口，可用于编程式切换：
 
-# 次版本更新 (1.0.0 -> 1.1.0)
-npm version minor
+### 获取当前环境
 
-# 主版本更新 (1.0.0 -> 2.0.0)
-npm version major
+```Plain Text
+GET /__mock_switch__/env
 ```
 
-### 3. 本地测试
+**响应：**
 
-```bash
-# 在插件目录
-npm link
+```json
+{
+  "currentEnv": "mock",
+  "environments": [
+    { "key": "mock", "name": "Mock环境", "target": null },
+    { "key": "dev", "name": "开发环境", "target": "http://localhost:8080" },
+    { "key": "prod", "name": "生产环境", "target": "https://api.example.com" }
+  ]
+}
+```
+
+### 切换环境
+
+```Plain Text
+POST /__mock_switch__/env
+Content-Type: application/json
 
-# 在测试项目
-npm link mock-switch-webpack-plugin
+{
+  "env": "dev"
+}
 ```
 
 ## ❓ 常见问题
 
-### Q: 为什么切换环境后需要刷新页面？
-A: 已发出的请求不会改变，新请求会走新环境。建议切换后刷新页面确保一致性。
+### Q: CRA 热重载后环境状态丢失？
 
-### Q: Mock 热更新不生效？
-A: 检查 `hotReload: true`，确保 Mock 文件在配置的 `mockDir` 目录下。
+A: 插件已内置全局状态持久化机制，使用 `createMockMiddleware` 即可自动处理。
 
-### Q: 如何处理 body 参数？
-A: 需在 devServer 中配置 `devMiddleware: { writeToDisk: true }` 或添加 body-parser 中间件。
+### Q: Mock 文件修改后不生效？
 
-### Q: 支持 RESTful 动态路由吗？
-A: 目前支持精确匹配，动态路由建议使用 JS Mock 函数处理。
+A: 确保 `hotReload: true`（默认开启），插件会自动清除 require 缓存。
 
-## 📝 更新日志
+### Q: POST 请求 body 为空？
 
-### v1.0.0 (2024-06-15)
-- ✅ 首次发布
-- ✅ 浏览器端环境切换面板
-- ✅ Mock 数据热更新
-- ✅ 真实接口自动记录
-- ✅ 一键保存为 Mock 文件
-- ✅ 自动路径匹配
+A: 插件已内置 express\.json \(\) 和 urlencoded 解析中间件，无需额外配置。
 
-## 🤝 贡献
+### Q: 代理请求 404？
 
-欢迎提交 Issue 和 Pull Request！
+A: 插件会自动移除 `apiPrefix` 前缀，如 `/api/users` → `/users`，确保后端接口路径正确。
 
 ## 📄 License
 
-MIT © Webpack Mock Switch Team
+MIT © [lebron\_shi](https://github.com/shilimingY)
+
+---
+
+
+
+**如果这个插件对你有帮助，欢迎给个 ⭐ Star**
+
+[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.2.0",
   "description": "前端Mock神器！浏览器一键切换Mock/开发/生产环境的Webpack插件，支持接口代理、Mock数据热更新、POST请求自动转发等特性，零配置接入React/Vue等所有Webpack项目，彻底告别需手动修改代码来切换环境的低效开发方式。",
   "main": "dist/index.js",
   "scripts": {